Multi-session Workflow

Multi-session work runs several tasks at the same time to cut down on waiting. It is useful when tasks can move independently, and risky when multiple agents edit the same files without ownership boundaries. The key to keeping it safe is isolating working directories so edits never collide.

Why Multi-session

In a single session you wait for each Claude response before starting the next task. With multiple sessions you keep other work moving in parallel.

Claude Code offers three broad mechanisms for parallel work:

• git worktrees: isolate file edits at the directory level.
• agent view (claude agents): dispatch and manage many background sessions from one screen.
• subagents / agent teams: distribute and coordinate the work itself inside one session.

This chapter covers the first two (worktrees and agent view). Subagents and agent teams are covered in the next chapter.

git worktrees: The Core Tool

Running multiple sessions against the same checkout causes file conflicts. A git worktree is a separate working directory with its own files and branch that shares the same repository history and remote as your main checkout. Giving each session its own worktree means you can build a feature in one terminal and fix a bug in another without either touching the other's files.

A clean pattern is one intent per worktree:

• Main session: integrates decisions and resolves conflicts.
• Implementation session: owns a specific file set or feature area.
• Verification session: runs checks, captures failures, and reports concrete evidence.

Automatic Isolation With --worktree

Pass --worktree (-w) with a name and Claude creates an isolated worktree and starts inside it. By default the worktree is created under .claude/worktrees/<name>/ at your repository root, on a new branch named worktree-<name>:

# Start Claude in a named, isolated worktree
claude --worktree feature-auth

# Start a second isolated session in another terminal with a different name
claude --worktree bugfix-123

# Omit the name and Claude generates one such as "bright-running-fox"
claude --worktree

Worktrees branch from your repository's default branch (origin/HEAD), so they start from a clean tree matching the remote. If no remote is configured or the fetch fails, the worktree falls back to your current local HEAD. To always branch from local HEAD, set worktree.baseRef to "head" in settings (the setting accepts only "fresh" or "head", not arbitrary git refs).

To branch from a specific pull request, pass the PR number prefixed with #, or a full GitHub pull request URL. The worktree is created at .claude/worktrees/pr-<number>:

claude --worktree "#1234"

The manual git worktree add flow still works and remains the right choice when you need to place a worktree outside the repository or check out a specific existing branch:

# Manual worktree on a new branch
git worktree add ../project-feature-auth -b feature-auth

# Manual worktree from an existing branch
git worktree add ../project-bugfix bugfix-123

# Run a separate Claude session in each worktree
cd ../project-feature-auth && claude

Copy gitignored Files Into Worktrees: .worktreeinclude

A worktree is a fresh checkout, so untracked files like .env or .env.local from your main repository are not present. Add a .worktreeinclude file to your project root and Claude copies the listed files when it creates a worktree:

# .worktreeinclude (uses .gitignore syntax)
.env
.env.local
config/secrets.json

Only files that match a pattern and are gitignored are copied, so tracked files are never duplicated. This applies to worktrees created with --worktree, subagent worktrees, and parallel sessions in the desktop app.

Enter and Exit a Worktree Mid-session

You can ask Claude to "work in a worktree" during a session and it creates one with the EnterWorktree tool, switching the session into it. ExitWorktree ends the worktree session and returns to the original directory. Passing a path to EnterWorktree switches to an existing worktree of the current repository instead of creating a new one — useful when you already have an isolated directory prepared. These tools are not offered to a subagent that already runs in its own working directory (for example one set to isolation: worktree).

Declarative Isolation in an Agent Definition

Set isolation: worktree in a subagent's frontmatter and that agent always runs in its own isolated worktree. Each subagent gets a temporary worktree that is removed automatically when it finishes without changes. Subagent worktrees use the same base branch as --worktree, so they branch from your repository's default branch unless worktree.baseRef is set to "head".

---
name: reviewer
description: Dedicated code-review agent
isolation: worktree
---

Managing Worktrees

# List worktrees
git worktree list

# Remove a worktree when you're done
git worktree remove ../project-feature-auth

# Prune stale entries
git worktree prune

Remember to initialize the development environment in each new worktree — install dependencies, set up virtual environments, or run whatever your project's setup requires.

Cleanup Behavior

When you exit a worktree session, cleanup depends on whether you made changes:

• No uncommitted changes, no untracked files, and no new commits: the worktree and its branch are removed automatically. If the session has a name, Claude prompts so you can keep it.
• Uncommitted changes, untracked files, or new commits exist: Claude prompts you to keep or remove the worktree. Removing deletes the directory and branch, discarding any uncommitted work.
• Non-interactive runs (--worktree with -p): there is no exit prompt, so worktrees are not cleaned up automatically. Remove them with git worktree remove.

WorktreeCreate / WorktreeRemove Hooks

Worktree creation and removal fire WorktreeCreate and WorktreeRemove hook events. A WorktreeCreate hook replaces the default git worktree logic entirely, so you can implement worktree isolation for non-git systems such as SVN, Perforce, or Mercurial. In that case .worktreeinclude is not processed, so copy any local config files inside the hook script.

agent view: Manage Many Background Sessions From One Screen

Agent view, opened with claude agents, is one screen for all your background sessions: what is running, what needs your input, and what is done. Each background session is a full Claude Code conversation that keeps running without a terminal attached, so you can open it, reply, and leave whenever you want.

# Open agent view
claude agents

# Show only sessions started under a directory (requires v2.1.141+)
claude agents --cwd ~/projects/my-app

Dispatching Background Sessions

• From the agent view input: type a prompt and press Enter. Every prompt starts a new session rather than sending a follow-up, so you can launch several in parallel.
• From inside a session: run /background (alias /bg) to move the current conversation to the background.
• ← on an empty prompt: backgrounds the current session and opens agent view in one step.
• From the shell: claude --bg "<prompt>" starts a session straight in the background.

# Start a background session from the shell
claude --bg "investigate the flaky SettingsChangeDetector test"

# Set a display name and run a specific subagent as the session's main agent
claude --bg --name "flaky-test-fix" --agent code-reviewer "address review comments on PR 1234"

After backgrounding, Claude prints the session's short ID and the commands to manage it.

How File Edits Are Isolated

Whether started from agent view, /bg, or claude --bg, every background session begins in your working directory. Before editing files, Claude moves the session into an isolated worktree under .claude/worktrees/, so parallel sessions can read the same checkout but each writes only to its own. Claude skips the worktree when the session is already inside a linked worktree, when the directory isn't a git repository (and no WorktreeCreate hook is configured), or when the write is outside the working directory.

For a repository where git worktrees are impractical, set worktree.bgIsolation to "none" so background sessions edit your working copy directly (requires v2.1.143+):

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Stopping and Deleting Background Sessions

From the shell, manage background sessions with:

claude attach <id>     # Attach to the session in this terminal
claude logs <id>       # Show recent output
claude stop <id>       # Stop the session (claude kill also works)
claude respawn <id>    # Restart with the conversation intact (e.g. to pick up an updated binary)
claude rm <id>         # Remove from the list (keeps a worktree with uncommitted changes, prints its path)
claude agents --json   # Print live sessions as a JSON array and exit

Background sessions are hosted by a per-user supervisor process. They keep running when you close agent view or your shell. Once a session finishes and sits unattached for about an hour the supervisor stops its process to free resources, except for sessions you pin with Ctrl+T. The next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off.

To turn off background agents and agent view entirely, set disableAgentView to true or set the CLAUDE_CODE_DISABLE_AGENT_VIEW environment variable.

Branch a Conversation With /branch

/branch copies the conversation so far into a new session and switches you into it, leaving the original intact. Use it to explore a different direction from the same context.

/branch try-streaming-approach

From the command line, combine --fork-session with --continue or --resume:

claude --continue --fork-session

The /branch confirmation prints two session IDs (the new branch and the original). To return to the original, pass its ID to /resume or use the session picker. Branches created with /branch, /rewind, or --fork-session are grouped under their root session in the session picker.

Naming and Resuming Sessions

Give sessions descriptive names so they are findable and resumable. Set a name with claude -n auth-refactor at startup, /rename auth-refactor during a session, or Ctrl+R in the session picker. Accepting a plan in plan mode names the session from the plan content unless you have already set one. Once named, return with claude --resume <name> or /resume <name>.

Resuming a session that lives in another worktree of the same repository switches into that worktree in place. In the session picker, Ctrl+W widens to all worktrees of the repository, Ctrl+A widens to every project on the machine, and Ctrl+B filters to the current git branch.

Persisting Sessions With tmux

In environments where you do not use agent view, tmux keeps a session alive even after the terminal closes. (Background sessions are persisted by the supervisor, so they survive without tmux.)

# Create sessions
tmux new-session -s auth
tmux new-session -s ui

# Reattach
tmux attach -t auth

Session Brief

Start every parallel session with a small contract:

You own only apps/handbook/app and apps/handbook/lib.
Do not edit content files.
Goal: make route generation locale-aware.
Report changed files and verification results.

The narrower the contract, the less coordination overhead the main session has to absorb.

Handoff Format

Ask every session to end with the same fields:

• Files changed.
• Behavior changed.
• Commands run.
• Known risks.
• Follow-up work.

This makes integration review mechanical instead of conversational.

Conflict Control

Avoid parallel edits to these areas unless one person owns the merge:

• Shared type definitions.
• Generated source files.
• Root package metadata.
• Test fixtures used by multiple suites.
• Route or middleware files that affect every request.

How Many Sessions

• Two: implementation plus review or research in parallel.
• Three: three mutually independent features at once.
• Four or more: only for simple repetitive work, and watch your rate-limit consumption.

When Not To Use It

Do not split work when the next step depends on the result of a single unknown. Investigate the blocking question locally first, then delegate once the shape of the change is clear.

Reference

• Run parallel sessions with worktrees: https://code.claude.com/docs/en/worktrees
• Manage multiple agents with agent view: https://code.claude.com/docs/en/agent-view
• Manage sessions: https://code.claude.com/docs/en/sessions
• git worktree: https://git-scm.com/docs/git-worktree
• tmux: https://github.com/tmux/tmux/wiki