# FAQ

> Frequently asked questions about crystl: platform, agents, gems and shards, isolated worktrees, quest, scheduling, pricing, security, and more.

Quick answers to the things people ask most. For a deep dive on any topic, follow the links to the full docs.

## Getting started

### What is crystl?

crystl is a macOS terminal built for coding agents. It lets you run many agents at once without getting lost in tabs and windows: every project is a **gem** with its own terminal **shards**, a screen-edge **[crystal rail](/docs/crystal-rail/)** keeps projects one click away, and **[action panels](/features/action-panels/)** float approvals and questions on screen so you answer the right agent without hunting. It also works as a normal terminal for any command-line work.

### Is crystl free?

Yes. The free tier includes isolated shards and parallel sessions, action panels, the [agent activity panel](/docs/agent-activity-panel/), split view, the [history navigator](/docs/conversation-history/), token tracking, the [workbench](/docs/task-backlog/), project optimizer, the agent file editor, screenshot and copy bars, MCP servers, API key storage, remote development over SSH, Metal-accelerated GPU rendering, facet inserts, and [agent scheduling](/docs/schedule-agents/) (up to 3 schedules). The **[Guild](/pricing/)** plan ($170/year) adds the Prompt Library integration, [formations](/docs/formations/), CLI orchestration (the control commands), unlimited scheduling, the iPhone app from anywhere, up to 3 devices, and priority support. See [Licensing](/docs/licensing/) for the full split.

### Does crystl work on Linux or Windows?

No. crystl is **macOS only**. It's a native Swift app and relies on macOS features like the Keychain for secure API key storage.

### Which agents does crystl work with?

Any CLI agent runs in crystl, since every shard is a full terminal session. The deeper integrations depend on what each agent exposes: **Claude Code** has the deepest integration, and **Codex** supports hooks too, so approval panels and notifications work for both. **Antigravity CLI** doesn't support hooks yet, so those features aren't available for Antigravity sessions, but everything else works.

### Can I use crystl for regular terminal work?

Yes. Every shard is a full terminal session: git, npm, docker, ssh, whatever you need. The agent-specific features are there when you want them and out of the way when you don't.

### Does crystl work fully with Codex?

Yes. Codex supports hooks, so approval panels and notifications work just like they do for Claude Code, and Codex sessions feed the [history navigator](/docs/conversation-history/) and token metrics. You can spawn Codex workers from the [CLI](/docs/cli/) (`--agent codex`) and mix Codex and Claude agents in the same workspace. Antigravity CLI runs too, but it doesn't support hooks yet, so approval panels and notifications aren't available for Antigravity sessions.

## Gems, shards & multitasking

### What are gems and shards?

A **gem** is a project workspace tied to a directory; a **shard** is a terminal session inside it. Think of gems as projects and shards as the tabs within each one. See [Gems & Shards](/docs/gems-and-shards/).

### How do gems, shards, and tabs fit together?

It's two levels. **Gems** are the top level, one per project, and you switch between them from the [crystal rail](/docs/crystal-rail/) (the screen-edge dock) or the **gem tab bar** across the top of the window. **Shards** are the sessions inside a gem, shown in the **shard bar** that appears once a gem has two or more; each shard is its own terminal and can hold its own agent session. The gem tab bar can sit across the top by default, or down the left side with **Sidebar Mode** on (Settings → General). Every gem always keeps at least one shard.

### How do I add another session versus another project?

Use the **+** on the **shard bar** to add another shard (session) to the *same* project. Use the **+** on the **gem tab bar** (or **New Gem** in the crystal rail) to open a *different* project. Mixing these up is the usual point of confusion: the shard-bar + stays inside the current gem, the tab-bar + opens a new one.

### How do I run multiple agents at once?

Open as many shards as you want inside a gem and run them side by side, and open multiple gems for different projects. [Isolated shards](/docs/isolated-sessions/) each get their own git worktree and branch, so several agents can work the same repo simultaneously without stepping on each other.

### How do I keep track of all my agents?

The [agent activity panel](/docs/agent-activity-panel/) shows every agent across your gems in one view: who's working, who's idle, and where tokens are going. [Action panels](/features/action-panels/) float approvals and questions as glass panels color-coded by project, so you respond to the right agent without switching windows.

### Why did my new shard open in a different directory than my last one?

Every shard starts at its gem's project directory by design, so a project's shards stay predictable no matter where any one of them has `cd`'d. crystl prints a hint in the new shard when this happens. Want the new shard to start where you are instead? Right-click (or control-click) the shard button. See [Gems & Shards](/docs/gems-and-shards/#where-shards-start).

### How do I get notified when an agent needs me or finishes?

crystl surfaces everything as floating **[glass panels](/docs/notifications/)** near your workspace: approval requests, questions the agent asks, denials, and activity notifications like "Claude finished." They're color-coded by gem, so you act on the right agent (click **Allow** / **Deny** or type a reply) without switching to that project. Panels dismiss on their own or on click.

### What are the approval modes?

Four, set globally or per gem: **Ask Every Time** (approve every tool call), **Smart** (auto-approve safe reads, prompt for writes and commands), **Auto** (approve everything, full speed), and **Pause** (queue requests without showing them until you switch back). See [Approval Modes](/docs/approval-modes/).

### What is the workbench?

A per-gem task list that slides out from the right edge of the terminal, backed by a plain `WORKBENCH.md` at the project root. You and the agent read and write the same file: add items, check them off, and send one straight to the active agent. See [Workbench](/docs/task-backlog/).

### I closed a shard by accident. Can I get it back?

Yes. crystl keeps a short **undo-close list** per gem, so a recently closed local shard comes back from the shard bar or `crystl resurrect` with its name, color, and best-effort isolation and agent session intact. (This is separate from the automatic session restore that brings everything back when you relaunch crystl.) See [Resurrecting Shards](/docs/resurrect-shards/). For recovering the agent conversation itself after a window or terminal closes, see [where did my agent session go](#where-did-my-agent-session-go-after-i-closed-the-window).

### Do my agents come back after I quit crystl?

Yes. A shard restored by crystl (whether from the session restore on relaunch or from an explicit resurrect) holds a **deferred relaunch**, and the first thing dispatched to it starts its agent on **its own conversation** before delivering the message. So a chat-dock message, a quest turn, a notification, or a `crystl send` reaches the agent you were talking to rather than landing in the shell underneath, and an overnight fan-out survives quitting the app. If a relaunch can't happen, the shard reports `⚠ no agent — relaunch failed` in `crystl shards` instead of looking healthy and silently swallowing what you send it. See [Resurrecting Shards](/docs/resurrect-shards/#a-restored-shard-relaunches-its-own-agent).

### What's a formation?

A named collection of gems (and optionally their shards) you save and reload as a group (including SSH'd gems and remote worktrees) so you restore a whole working layout in one click instead of opening projects one by one. Set one as the default to auto-load on launch. Formations are a [Guild](/pricing/) feature. See [Formations](/docs/formations/).

## Isolated shards & worktrees

### What are isolated shards?

Isolated shards use **git worktrees** to give each agent its own working copy of the repo on a separate branch, so parallel agents never collide. crystl also installs dependencies and symlinks your `.env` automatically. See [Isolated Sessions](/docs/isolated-sessions/).

### Can I start a worktree from a specific branch?

Yes. Click the worktree button for a fresh branch off your default, or **control-click (or right-click)** it for the worktree menu: **new isolated shard from branch…** forks from any branch, tag, or checkout. From the CLI it's `crystl shard create --isolated --base <ref>`. See [Isolated Sessions](/docs/isolated-sessions/#the-worktree-menu).

### Where did the isolation button go?

Its jobs moved closer to what they act on. Creating an isolated shard now uses the worktree button in the shard bar (or the File menu). Merging and rebasing live on each shard's tab: a shard with unmerged commits shows a small **↑N** badge you can click, and every action names the branch, target, and commit count. A **branches** button appears only when parked worktree branches exist, so you can reattach, merge, or discard them.

### What happens to my branch when I close an isolated shard?

crystl prompts you: **Merge to Main** (rebase + fast-forward, then close), **Keep Branch** (preserve it to reopen later), or **Discard** (delete it). Parked branches are reachable again from the branches button. See [merging back](/docs/isolated-sessions/#merging-back-to-main).

## Quest & heroes

### What is crystl quest?

[crystl Quest](/docs/crystl-quest/) launches a party of role-played agents (each a named **hero** with a role, stats, and model) into a shared chat where they divide the work, coordinate, and report back. Heroes also work solo as a [hero shard](/docs/hero-shards/) without a whole party.

### What heroes ship with crystl?

15 core heroes ship built in (Wizard, Ranger, Rogue, Paladin, Druid, Bard, Monk, Healer, Seeker, Sentinel, Dwarf, and more). The **sync from crystl.dev** button on the Heroes page expands the catalog to the full roster, currently 30, all [browsable in the Library](/library/heroes/). You can also build your own; see [Quest Heroes](/docs/quest-heroes/) and [pricing](/pricing/) for what's included per tier.

### How many agents can be in a quest party?

A party is flexible: pick from the built-in templates or assemble your own set of heroes. See [Starting a Quest](/docs/starting-a-quest/).

## Automation, CLI & scheduling

### What is the crystl CLI?

A built-in `crystl` command lets you (and agents) drive gems, shards, and approvals from any shell. **Read commands are free** (`status`, `gems`, `shards`, `screen`, `history`, `docs`, and more); the **control commands** that change something (`open`, `shard create`, `send`, `approve`, `merge`, `quest start`, …) need [Guild](/pricing/). See the [CLI reference](/docs/cli/).

### Can I schedule an agent to run on its own?

Yes. [Agent scheduling](/docs/schedule-agents/) launches a fresh agent at a set time, once or on a daily/weekdays cadence, with its own gem, prompt, agent, model, and approval mode. Set it up in **Settings → Agents → Schedules** or via `crystl schedule add`. It's free up to 3 active schedules on every tier; a Guild membership lifts the cap.

### What is the CLAUDE.md manager / agent file editor?

The [agent file editor](/features/agent-config-editor/) creates and edits `CLAUDE.md`, rules, skills, and other agent config files with a block editor and file chooser, and manages named starter templates you can drop into new projects.

## Config, security & the app

### Where are my API keys stored?

In the macOS **Keychain**. See [API Key Storage](/docs/api-keys/). Your code, terminal output, and conversations stay on your Mac; crystl's own network calls are limited to license and update checks. See the [Privacy](/privacy/) page for details.

### How do MCP servers work?

Configure [MCP servers](/docs/mcp-servers/) per gem so the right tools and data sources load for each project.

### Is there an iPhone app?

Yes. [crystl for iPhone](/features/mobile/) is on the App Store. It pairs to your Mac to monitor, approve, and steer agents. Same-Wi-Fi pairing is free; connecting from anywhere over the encrypted relay is a Guild feature.

### Can I use crystl on a remote server over SSH?

Yes. SSH into any machine from a shard and every crystl feature keeps working: approval panels, file drag-and-drop, click-to-open, and even isolated worktrees created on the remote host. It's free on every tier. See [Remote SSH Sessions](/docs/remote-ssh/).

### How do the copy bar and facet inserts work?

The **copy bar** sits under the terminal: an agent stages text there and you copy it with one click (editable, up to 10 tabs), handy for tokens, commands, or snippets you'd otherwise drag-select. **[Facet Inserts](/docs/facet-inserts/)** are the reverse: saved prompts you fire *into* the terminal with one click, instead of retyping the same instructions. Both are free.

### How do I update crystl?

crystl has a built-in updater that checks crystl.dev for new versions and notifies you when one is available, so you can install it without leaving the app. You can also download the latest build any time from your [account page](https://crystl.dev/account/). See the [changelog](/changelog/) for what's new in each release.

## Pricing & comparisons

### How much is Guild, and how many devices?

Guild is **$170/year**, auto-renewing, and covers **up to 3 devices**. Cancel anytime; there's a 14-day refund window. See [pricing](/pricing/) and [Licensing](/docs/licensing/).

### How do I activate my Guild license, and where's my key?

When you buy Guild, a license key is emailed to you automatically (from **chris@updates.crystl.dev**). In crystl, go to **Settings → License**, paste the key, and you're set. It's stored in your macOS Keychain, so you won't re-enter it unless you reinstall or switch machines. Lost the key? Search your email for that sender, or [contact support](/contact/). See [Licensing](/docs/licensing/).

### What's the best terminal for Claude Code?

crystl is built specifically for it: every shard runs the Claude Code CLI, and crystl adds what a plain terminal can't: parallel sessions, hook approvals as on-screen panels, per-project `CLAUDE.md` management, and token/context tracking. It's also a fine everyday terminal.

### Can I use crystl instead of tmux?

Yes, and it's built for it. tmux multiplexes panes but knows nothing about your agents. crystl is agent-aware: it groups sessions into projects, gives each isolated agent its own worktree and branch, and floats approvals and questions as panels instead of burying them in a pane you have to switch to.

## Gems, repositories & Git

### What is the difference between a gem and a Git repository?

A **gem** is a crystl workspace tied to a directory. It holds that project's shards, appearance, approval behavior, and other crystl settings. A **Git repository** is the directory tree and history managed by Git. A gem can point at a repository root, a folder inside a larger repository, or a directory that does not use Git at all. See [Gems & Shards](/docs/gems-and-shards/).

### Does every gem need its own Git repository?

No. Shared shards work in any directory, including non-Git folders and subfolders of a larger repository. A gem needs to be its own repository root only when you want [isolated shards](/docs/isolated-sessions/), because each isolated shard needs a Git branch and worktree rooted at that gem.

### What happens when I create a gem inside an existing repository?

crystl warns that the new folder belongs to a larger repository and offers two choices. **Use shared shards** leaves the folder in its parent repository. **Make standalone repo** initializes a separate repository inside the folder. Both choices create the gem; only the second creates separate Git history.

### What do "Use shared shards" and "Make standalone repo" mean?

**Use shared shards** means every ordinary shard works in the same checkout as the parent repository. It is the default. **Make standalone repo** creates a nested Git repository whose history belongs to the gem, which makes isolated shards possible. Choose the standalone option only when that separate history is intentional.

### Why is "Use shared shards" the default?

A folder inside a larger repository is usually meant to remain part of that repository. Silently turning it into a nested repository changes Git boundaries, history, and tooling behavior. crystl therefore preserves the existing repository structure unless you explicitly request a standalone repository.

### Why is "Initialize Git repository" turned off by default?

Creating a crystl workspace and creating a Git repository are separate decisions. Leaving the checkbox off avoids adding Git history to folders that belong to a monorepo, use another version-control system, or do not need version control. Turn it on when the new gem directory should be its own repository.

### Why can't this gem create isolated shards?

The gem must point at the root of a Git repository with at least one commit. crystl refuses isolation when the directory is not a repository, when its Git root is a parent folder, or when Git cannot safely create the worktree. For the first two cases, crystl can offer a **git init here** card. That action is explicit because it creates new history in the gem's folder.

### What is the difference between a shared shard and an isolated shard?

A **shared shard** is another terminal in the gem's existing working directory. All shared shards see and edit the same files. An **isolated shard** gets its own Git worktree and `crystl/{name}` branch, so its uncommitted files and commits do not collide with work in the main checkout. See [Isolated Sessions](/docs/isolated-sessions/).

### Does an isolated shard create a branch, a worktree, or both?

Both. The branch holds the isolated commit history, and the worktree supplies a separate working directory checked out on that branch. Local worktrees normally live under `.crystl/worktrees/{name}` in the repository.

### Can multiple gems point to folders inside the same repository?

Yes. This can be useful for a monorepo with distinct services or packages. Those gems still share one Git checkout and history, so edits and Git operations in one gem are visible to the others. Use isolated shards from the repository-root gem when parallel work needs separate working copies.

## Opening & creating gems

### What is the difference between "New Gem" and "Open Gem"?

**New Gem** creates a new directory and lets you choose its name, appearance, MCP servers, starter kit, and optional Git setup. **Open Gem** points crystl at a directory that already exists. Opening does not implicitly run `git init`, add a remote, or make an initial commit.

### Does opening an existing folder as a gem modify its files?

It can create or update a small set of user-controlled integration files. crystl ensures `.crystl/.gitignore` exists, may create `.mcp.json` from your enabled MCP catalog when that file is absent, and may maintain the marked crystl CLI section in agent instruction files when **tell agents about the crystl CLI** is enabled. If a project has MCP servers and MCP auto-trust is enabled, crystl may also merge the trust flag into `.claude/settings.local.json`. It does not initialize Git or create commits merely because the folder was opened.

### Which files can crystl create inside an existing project?

Opening a gem can involve these integration files, depending on your settings and the files already present:

- `.crystl/.gitignore`, which keeps crystl runtime state from dirtying Git status.
- `.mcp.json`, when enabled MCP defaults exist and the project does not already have that file.
- `.claude/settings.local.json`, when MCP auto-trust is enabled and the project has MCP servers.
- `AGENTS.md` and `CLAUDE.md`, when CLI instruction injection and creation of missing agent docs are enabled.

Other files under `.crystl/` are created when you use features such as history, worktrees, quest, local heroes, or per-gem settings. See [Settings](/docs/settings/), [Agent Files](/docs/agent-files/), and [MCP Servers](/docs/mcp-servers/).

### Will crystl overwrite an existing `AGENTS.md`, `CLAUDE.md`, or MCP configuration?

It does not replace whole agent instruction files. The CLI primer is enclosed by `crystl-cli` markers, and crystl updates only that managed section while preserving the rest of the file. On ordinary gem open, an existing `.mcp.json` is left alone. Explicit MCP changes from Gem Settings update crystl-managed entries while preserving entries outside crystl's catalog.

### Does closing a gem delete its folder, repository, or shards?

Closing a gem removes it from the current crystl workspace and stops its terminal sessions. It does not delete the project folder or ordinary Git history. If the gem contains isolated shards with unmerged commits or dirty worktrees, crystl asks whether to keep the branches, discard them, or cancel. **Discard** is the destructive choice; the other paths preserve work.

### What if I open a folder that is already inside a crystl worktree?

That folder is already a checkout of an isolated branch. Opening it as another gem does not create a second layer of isolation; it treats the checkout as an ordinary gem and can leave two crystl entries referring to the same worktree. Prefer the shard bar's **branches** button or **open orphaned worktree** action when you are recovering a crystl-managed worktree.

## Settings

### What is the difference between global, gem, and shard settings?

**Global settings** are app-wide defaults, such as appearance, terminal behavior, agent defaults, the MCP catalog, and the default worktree target. **Gem settings** override project behavior such as approval mode, agent setup, MCP selection, identity, and integration target. A **shard** is a running terminal inside the gem; it has identity and lifecycle actions, but no broad settings page of its own.

### Where do I change settings for one gem only?

Open the gem's three-dot menu and choose **Gem Settings**. Its **general**, **agents**, and **worktrees** tabs contain project-specific controls. Do not use app Settings when the change should affect only one project.

### What is available under the gem three-dot menu?

The gem menu includes history, **Gem Settings**, the project optimizer, recently closed shard recovery, and a per-gem approval shortcut. Some rows appear only when they apply. The Gem Settings panel has **general**, **agents**, and **worktrees** tabs. See [the gem menu](/docs/gems-and-shards/#the-gem-menu).

### What is available under the shard three-dot menu?

The shard menu contains actions for that terminal: rename, details, turn history, close, and branch actions such as merge or rebase when the shard is isolated. Rows are conditional, so a shared shard does not show isolated-branch actions. There is no separate Shard Settings screen. Shards inherit the gem's effective settings.

### Where do I configure approval behavior for a specific gem?

Use the approval shortcut in the gem menu or open **Gem Settings → general**. A per-gem approval choice overrides the global default for that project. See [Approval Modes](/docs/approval-modes/).

### Where do I choose the integration branch for isolated shards?

Set the global default in **Settings → Worktrees**. Override it for one gem in **Gem Settings → worktrees**. The CLI can also read or change the target with `crystl worktree target`. See [Integration target](/docs/isolated-sessions/#integration-target).

### Where are agent files, skills, plugins, rules, and starter kits configured?

Use **Settings → Library** for reusable starter kits, file templates, skills, and rules. Use **Gem Settings → agents** to manage the actual root instruction files and the Claude plugins, skills, and MCP servers included for one project. See [Plugins & Skills](/docs/plugins-and-skills/) and [Agent Files](/docs/agent-files/).

### Do settings changes affect existing shards or only new ones?

It depends on the setting. Appearance and gem identity update live. Approval changes apply to later approval decisions. Settings that define a terminal process (its renderer, scrollback, environment, agent launch command, or startup directory) apply when a shard is created and normally require a new shard. Worktree settings govern later isolated-shard creation and integration operations.

## Git safety

### Will crystl run `git init` without asking?

No. Git initialization follows an explicit action: selecting **Initialize Git repository** in New Gem, choosing **Make standalone repo** in the nested-repository warning, clicking **git init here**, or running `git init` yourself. Opening a folder or creating a shared shard does not initialize Git.

### Will crystl create commits automatically?

Only in explicit repository-setup flows. When crystl initializes a repository, it creates the first commit so Git can create worktrees from it. crystl's isolated-shard merge uses rebase plus fast-forward rather than an unnecessary merge commit. Opening an existing gem does not create a commit.

### Does opening a gem change its Git history?

No. Opening does not create branches, commits, tags, remotes, or rebases. It may create the integration files described above, so the working tree can change, but Git history does not.

### Can shared shards edit the same working tree at the same time?

Yes. Every shared shard in a gem sees the same checkout, including uncommitted edits. That is convenient when the terminals cooperate on one state, but two agents can overwrite or conflict with each other if they edit the same files concurrently. Use isolated shards when parallel agents need independent working copies.

### How do I merge or rebase an isolated shard?

Use the merge badge or the isolated shard's three-dot menu. **Rebase** brings the integration target into the shard while you keep working. **Merge** rebases the shard onto its target, fast-forwards the target, and cleans up. From the CLI, `crystl merge --gem <gem> --shard <shard>` uses the same guarded flow. crystl never forces through dirty worktrees or conflicts. See [Isolated Sessions](/docs/isolated-sessions/#merging-back-to-main).

### How can I tell which repository and branch a shard is using?

Open the shard's three-dot menu and choose **details**, or inspect it from the CLI with `crystl shards --gem <gem>`. Inside the shard, ordinary Git commands are authoritative:

```bash
pwd
git rev-parse --show-toplevel
git branch --show-current
```

A shared shard normally reports the gem's checkout and current branch. An isolated shard reports its `.crystl/worktrees/{name}` checkout and `crystl/{name}` branch.

## Running multiple agents

General questions about parallel agents, answered for any setup. The crystl-specific version of each is above.

### How do I get my AI agents to talk to each other?

Agents talk through a shared surface, never directly. Inside one session, subagents report their result back to the agent that spawned them, and Claude Code's `SendMessage` tool lets the parent resume a named subagent with follow-up instructions. Across separate sessions, the shared surface is a file both agents read and write, or an orchestration layer that relays messages between terminals.

The file approach is the portable one: a task list, a scratch directory, or a status document at a path both agents know. It survives restarts and works with any agent. crystl adds the relay layer: `crystl screen` reads another shard's terminal and `crystl send` types into it, so a lead agent can dispatch work and read the reply. [Side Quest](/docs/side-quest/) opens a 1:1 channel between two shards, and [crystl quest](/docs/crystl-quest/) puts a whole party in one shared chat. See [subagents](/guides/claude-code-subagents/) and the [CLI reference](/docs/cli/).

### How do I know which agent is waiting on my approval?

In a plain terminal, you don't. Nothing marks a blocked tab, so you cycle through windows until you find the prompt, which is why people miss agents parked for twenty minutes on a one-key answer. The fix is to route approvals somewhere outside the tab that raised them.

crystl does this with [action panels](/features/action-panels/): each approval floats on screen as its own panel, color-coded by project and naming the agent, gem, and tool it wants to run, so you answer without hunting. The [agent activity panel](/docs/agent-activity-panel/) lists every agent and its state in one view, and `crystl pending` prints the queue from any shell. See [managing multiple AI sessions](/guides/managing-multiple-ai-sessions/).

### Why do my agents keep overwriting each other's files?

Because they share one working directory. Two agents in the same checkout read and write the same files, and neither git nor the agents themselves arbitrate: the second write wins, silently, and the first agent keeps reasoning about a file that no longer says what it thinks. Prompting them to stay in their lane does not hold, because agents refactor across file boundaries.

The symptom to look for is an agent citing a version of a file that no longer exists, or a change you watched land reappearing undone a few minutes later. Check `git status` and `git diff` while both agents are running: if the working tree is moving under one agent's feet, that is the collision. Full breakdown of the failure modes: [why your AI agents keep overwriting each other's files](/blog/agents-overwriting-files/). For the setup that prevents it, see [how do I stop agents stepping on each other in one repo](#how-do-i-stop-agents-stepping-on-each-other-in-one-repo) below.

### How many agents can I run at once?

Your attention is the limit, not the tooling. Most people settle around three to five concurrent agents, because every agent produces work you have to review, and review does not parallelize. Machine resources rarely bind first; context and money do, since each agent burns its own tokens.

Claude Code caps concurrent subagents inside a single session at 20 by default, configurable with `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`. Separate top-level sessions have no such cap, so the ceiling there is genuinely yours. See [how many agents can you actually run](/blog/how-many-agents-can-you-run/) and [running multiple Claude Code instances](/blog/run-multiple-claude-code-instances/).

### How do I run agents on different branches at the same time?

Use git worktrees. `git worktree add ../feature-x -b feature-x` creates a second directory checked out on its own branch, backed by the same repository and history, and you start an agent in each directory. Branch switching in one worktree never disturbs the others.

Worktrees do not copy ignored files, so each new directory needs its own `node_modules`, `.env`, and build cache before an agent can work there. See [git worktrees for parallel development](/guides/git-worktrees-parallel-development/). crystl's [isolated shards](/docs/isolated-sessions/) wrap the same mechanism and handle the install and `.env` symlink automatically.

### What happens to an agent when I close the terminal tab?

The agent process receives a hangup and stops mid-task. Files it already wrote stay written, and the turn it was in the middle of is lost, but the transcript is on disk, so the conversation is recoverable even though the process is not. Closing a tab is not a pause.

To survive tab closes deliberately, either start the agent detached (`claude --bg`, managed with `claude agents`) or run it inside a multiplexer session you can reattach to. See [tmux for AI agents](/guides/tmux-for-ai-agents/). In crystl, a closed shard lands on a per-gem undo-close list and comes back with its name, isolation, and agent session intact: see [Resurrecting Shards](/docs/resurrect-shards/).

### How do I give two agents the same task and compare results?

Give each agent its own branch and worktree, hand both the identical prompt, and diff the branches when they finish. `git diff main..attempt-a` against `git diff main..attempt-b` shows you two independent solutions to the same problem, and you keep the better one or cherry-pick from both.

This works because the attempts never share a working directory, so neither can contaminate the other's output. It is worth doing when the approach is genuinely uncertain, and wasteful when the task has one obvious shape. See [git worktrees for parallel development](/guides/git-worktrees-parallel-development/) and [running two agents on the same repo](/blog/two-agents-same-repo/).

### Can one agent hand work off to another when it finishes?

Yes, through hooks or an orchestrating parent. Within one session, a subagent's final report returns to the agent that spawned it, which then decides what to run next: that is the built-in handoff. Across separate sessions, a Stop hook fires when an agent ends its turn, and the command it runs can launch or message the next agent.

Keep the handoff payload in a file rather than a message, since the receiving agent starts with a fresh context window and only sees what it can read. A short status document beats a long prompt. See [subagents](/guides/claude-code-subagents/) and [Claude Code agents](/guides/claude-code-agents/); in crystl, `crystl send` and `crystl notify` do the cross-shard version.

### How do I stop agents stepping on each other in one repo?

Isolate the filesystem rather than relying on prompt instructions. Give each agent its own [git worktree](/guides/git-worktrees-parallel-development/) and branch before you start them, which removes the whole class of collision because there is no shared file left to race on. If they must share a checkout, split ownership by directory and let only one agent touch shared-by-nature files: lockfiles, migrations, generated schemas, route manifests.

Sequence the merges too. Parallel work that all lands at once produces conflicts nobody has context for, so integrate one branch at a time and let the next agent rebase onto the result. See [two agents, one repo](/blog/two-agents-same-repo/); in crystl, [isolated shards](/docs/isolated-sessions/) create the worktree and branch for you and handle the merge back.

### What's the difference between a subagent and a separate session?

A subagent runs inside another agent's session: it starts with a fresh context window, receives only the task prompt it was handed, and reports a summary back to its parent when it finishes. A separate session is its own top-level conversation with its own transcript, its own terminal, and no parent to report to.

The practical difference is who holds the thread. Subagents keep the main conversation's context clean, since only their conclusion comes back, and they suit bounded research or review work. Separate sessions suit long-running independent work you want to steer directly, resume tomorrow, and put on its own branch. See [Claude Code subagents](/guides/claude-code-subagents/) and [managing multiple AI sessions](/guides/managing-multiple-ai-sessions/).

### How do I get notified when an agent finishes if I'm away from the machine?

Route the finish signal off the desk. Claude Code and Codex both fire a Stop hook at the end of a turn, and the hook runs any command you point it at, so a Slack webhook, an SMS API call, or a push service reaches you wherever you are. A `say` or a desktop banner only works if you are sitting there.

Hooks tell you *something* finished, not *which* project, so give each gem or repo its own hook message before you rely on it. [crystl for iPhone](/features/mobile/) does this natively: it pushes activity and approval requests to your phone, over the local network for free or from anywhere on [Guild](/pricing/). For the on-screen version at your desk, see [how do I get notified when an agent needs me or finishes](#how-do-i-get-notified-when-an-agent-needs-me-or-finishes) above.

### Where did my agent session go after I closed the window?

It is still on disk. Claude Code writes every session transcript under `~/.claude/projects/`, keyed by working directory, so `claude --resume` in that directory lists your past sessions and reopens the one you pick, with full history. `claude --continue` skips the picker and resumes the most recent one.

Two things to know: the picker is scoped to the directory you run it from, so resuming from the wrong path shows an empty list, and transcripts are cleaned up after a retention period (30 days by default, `cleanupPeriodDays`). See [I lost my Claude Code session](/blog/lost-claude-code-session/). crystl keeps its own searchable [conversation history](/docs/conversation-history/) per shard, and a shard you closed by accident can be brought back whole with [undo-close](/docs/resurrect-shards/), covered under "I closed a shard by accident" above.

---
Source: https://crystl.dev/docs/faq/