Isolated Sessions

Isolated sessions let you run multiple Claude Code agents on the same repository simultaneously, each on its own git branch. Under the hood, Crystl uses git worktrees to give each agent a separate working copy — either on your Mac or on a remote server over SSH.

How It Works

When you create an isolated shard, Crystl:

1. Creates a new git worktree from your current branch
2. Detects your package manager and installs dependencies
3. Symlinks gitignored .env files from the main project
4. Tells Claude it’s in an isolated worktree (via system prompt) so it stays scoped to its task
5. Opens a terminal session in that worktree directory
6. Marks the shard with a branch icon so you can tell it apart from regular shards

Each isolated shard has its own copy of the repo on its own branch. Claude agents working in different isolated shards can edit the same files without conflicts.

Creating an Isolated Shard

Create an isolated shard from the Crystal Rail or shard menu (Option+click the ”+” in the shard bar). Crystl will prompt you to name the branch (or auto-generate one). The new shard opens in the worktree directory, ready for a Claude session.

Local vs. Remote Isolation

An isolated shard runs wherever its gem is currently working. Any shard in Crystl falls into one of four states:

State	Shell	Git worktree	How to create
Local	Your Mac	—	Click ”+” in a local gem
Local isolated	Your Mac	On your Mac	Option+click ”+” in a local gem
SSH’d	Remote server	—	Open an SSH gem or shard
Remote isolated	Remote server	On the remote server	Option+click ”+” in a gem with an active SSH shard

When you Option+click ”+” in a gem that already has an SSH shard, Crystl detects the existing remote session and creates the worktree on the remote server instead of locally. You get all the isolation benefits — parallel agents, branch tracking, merge-on-close — without pulling the repo to your Mac first.

Remote Isolated Shards

Remote isolation piggybacks on Crystl’s existing SSH ControlMaster connection to run git commands on the remote host.

Creation flow

When you Option+click ”+” in a gem that has a live SSH shard, Crystl:

1. Detects the SSH shard in the current gem and reuses its RemoteSession (ControlMaster socket).
2. Finds the remote git root by running git rev-parse --show-toplevel over SSH from the current remote working directory.
3. Creates the worktree remotely:

   git worktree add -b crystl/{crystal-name} .crystl/worktrees/{crystal-name}

4. Symlinks config files on the remote so Claude picks them up: CLAUDE.md, .mcp.json, .claude/.
5. Writes .crystl/worktrees/{crystal-name}/autorun.sh on the remote. The autorun wraps claude with --append-system-prompt so the agent knows it’s isolated (see Agent Context).
6. Opens a new SSH shard to the same host and cds into the remote worktree path.
7. Tracks remoteWorktreePath and remoteProjectDir on the session so merge/close operations can find the right files later.

The new shard behaves like any other SSH shard — command history, approval panels, click-to-open — but its git state lives on the remote.

Non-git remotes

If git rev-parse --show-toplevel fails on the remote (not a git repo), Crystl falls back to creating a plain remote shard at the current directory, same as a normal SSH ”+” click. No worktree, no branch, no warning — just a regular remote session.

Agent Context

When Claude starts in an isolated shard (local or remote), Crystl injects this context via --append-system-prompt:

You are working in an isolated worktree on branch {branch}. Other agents may be working on the same repo in parallel. Keep your changes scoped to your task. IMPORTANT: Do not merge, cherry-pick, or rebase your branch into main. Crystl handles branch integration when the shard closes.

You don’t need to add any of this to your prompt. The branch name is substituted in at session start, so Claude knows exactly which worktree it’s in. This prevents the common problem of agents cherry-picking commits, rebasing onto main, or pushing to the wrong branch.

Use Cases

Parallel Feature Work

Give two Claude agents different tasks on the same repo:

• Shard A (isolated): “Add user authentication to the API”
• Shard B (isolated): “Write integration tests for the payment flow”

Both agents work at full speed without stepping on each other’s changes.

Explore vs. Implement

Use one isolated shard for Claude to prototype an approach while you continue working in your main shard. If the prototype looks good, merge it in. If not, discard the worktree.

Code Review Assistance

Create an isolated shard to have Claude review and suggest improvements to a feature branch while you continue developing on another.

Automatic Workspace Setup

Crystl detects your package manager from lockfiles and runs the install command when the workspace opens. Gitignored .env files are symlinked from the main project so they’re available immediately.

Supported package managers: npm, pnpm, yarn, bun, pip, poetry, uv, pipenv, bundler, composer, cargo, go, mix, swift, and cocoapods.

Custom setup

For projects that need additional setup steps (starting Docker containers, running migrations, etc.), add a setupCommand to .crystl/project.json:

{ "setupCommand": "docker compose up -d" }

Crystl runs the custom command after dependency installation.

Reopening Worktrees

When you close an isolated shard with Keep Branch, the branch is preserved in git history — locally for local isolated shards, on the remote server for remote isolated shards. You can reopen it later from the Isolation ▾ panel in the shard bar.

Under the Open section, Crystl lists all orphaned crystl/* branches that aren’t attached to an active session. Each entry shows the branch name and whether it has commits or uncommitted changes. Click one to reattach the worktree and resume where you left off.

If the worktree directory still exists (e.g., after a crash or restart), Crystl reuses it as-is — your uncommitted changes are preserved. If only the branch remains, Crystl recreates the worktree from it.

Remote orphaned branches

When the current gem has an active SSH shard, the Isolation panel also lists orphaned crystl/* branches found on the remote server. Crystl queries them asynchronously over the existing SSH connection, so the panel opens immediately and populates remote entries as the query returns.

Clicking a remote orphaned branch reopens it on the remote: if .crystl/worktrees/{name} still exists on the server, it’s reused as-is; otherwise Crystl recreates the worktree from the branch. Either way, the new shard SSHs back into the same host and lands in the worktree directory.

Stale branch recovery

When you create a new isolated shard and Crystl detects a leftover branch with the same name, it handles it automatically:

• Existing intact worktree — reused as-is, preserving uncommitted changes
• Stale branch with commits — Crystl reattaches the worktree to the existing branch
• Stale branch with no commits — Crystl prunes the reference and creates fresh
• No stale branch — creates a new worktree and branch as normal

Merging Back to Main

When an isolated shard’s work is complete, there are two ways to merge. Both work identically for local and remote isolated shards — for remote shards, Crystl runs the same git commands over SSH against the remote repository.

From the Isolation panel

Click Isolation ▾ in the shard bar to open the management panel. Under Selected Shard, choose Merge to main — Crystl rebases the shard’s branch onto main, fast-forward merges, and cleans up the worktree automatically. The shard closes after a successful merge.

You can also choose Rebase onto main to pull in upstream changes without merging — useful when you’re still working but want to stay up to date.

On shard close

When you close an isolated shard that has commits, Crystl prompts you:

• Merge to Main — rebase + fast-forward merge, then close
• Keep Branch — close the shard, branch is preserved for later
• Discard — delete the branch and all its commits

For remote isolated shards, the exact same prompt appears — but the git operations run on the remote server over the session’s SSH ControlMaster, against remoteProjectDir and remoteWorktreePath. The worktree directory and branch on the remote are cleaned up when you choose Merge to Main or Discard.

When closing a gem with multiple unmerged branches, you’ll see Keep Branches / Discard All / Cancel.

Process exit auto-close (e.g., when an agent finishes) skips the prompt so it doesn’t interrupt your work in other shards.

Conflict handling

If the rebase encounters conflicts, Crystl aborts the rebase automatically and tells you what went wrong in the terminal. You can resolve conflicts manually with git rebase main and then merge when ready. For remote isolated shards, run the resolution commands in the remote shard itself — you’re already SSH’d into the right directory.

Schema change warnings

When multiple isolated shards are modifying database schema or migration files at the same time, Crystl warns you before merging. This helps avoid the common problem where parallel migration files conflict — merge one shard first, regenerate migrations, then merge the next.