skip to content

How do you run two Claude Code sessions on one repository at once without colliding edits, and what does `claude --worktree` set up?

level: juniorimportance: must knowfreq 26%

answer

  1. a separate checkout per session
  2. one flag, an optional name
  3. a hidden folder at the repository root
  4. a new branch prefixed worktree-
  5. the exit check decides keep or remove

basics

~20 s

Start each session with claude --worktree <name> (or -w). Claude Code creates a git worktree at .claude/worktrees/<name> on a new branch worktree-<name> and starts there, so each session edits its own files while sharing the repository history.

solid answer

~40 s

Run `claude --worktree feature-auth` in one terminal and `claude -w bugfix-cache` in another. Each creates a git worktree at `.claude/worktrees/<name>/` on a new branch `worktree-<name>`, branched by default from the repository's default branch on the remote rather than from your current `HEAD`, and starts Claude inside it; omit the name and Claude Code generates one. The sessions share the repository's `.git` directory but not their working files, and while a session is isolated Claude Code blocks edits, commands and git redirects that would reach back into the main checkout. On exit Claude Code checks the worktree: a clean, unnamed one is removed together with its branch, and one holding changes or new commits prompts you to keep or remove it. Add `.claude/worktrees/` to `.gitignore` so the folders don't show up as untracked files.

code

bash · 8 lines
bash
# terminal 1
claude --worktree feature-auth

# terminal 2
claude -w bugfix-cache

# keep the worktree folders out of git status
echo '.claude/worktrees/' >> .gitignore

go deeper

for a junior

Recall the command, claude --worktree with a name or -w, and where it puts things: .claude/worktrees/<name> on a branch called worktree-<name>.

for a middle

Explain why separate working directories prevent collisions, what the session still shares through .git, that the default base is the remote default branch, and what the exit check does with clean and dirty worktrees.

for a senior

Show you know isolation is enforced by blocking edits, commands and git redirects into the main checkout, and that -p runs leave worktrees and locks behind for you to clean up.

for a principal

Frame worktrees as the cheap layer of parallelism: isolation of files only, so decide where coordination, review and merge of several branches will happen before scaling to many sessions.

## The problem: two agents, one working tree Claude Code edits files and runs commands in the directory it was started in. Start two sessions in the same checkout and they share one set of files: one session's half-finished edit breaks the other's test run, both rewrite the same module, and a `git checkout` in one silently changes the ground under the other. Asking each session to be careful does not help, because nothing in an instruction file can stop a tool call. The fix is to give each session its **own working directory** while keeping one repository. A **git worktree** is exactly that: a second working directory with its own files and its own branch, attached to the same repository history and remote as your main checkout. Git's own worktree commands are their own subject; what matters here is that Claude Code can create and manage one for you. ## What `--worktree` creates Pass `--worktree` (short form `-w`) with a name: | Piece | Default | What changes it | |---|---|---| | Location | `.claude/worktrees/<name>/` at the repository root | a `WorktreeCreate` hook that replaces the git logic | | Branch | a new branch `worktree-<name>` | passing `#1234` or a pull/merge request URL fetches that change instead | | Starting commit | the default branch on the remote (`worktree.baseRef` is `"fresh"`) | `worktree.baseRef: "head"` branches from your local `HEAD` | | Name | the one you pass | omitted, Claude Code generates one such as `bright-running-fox` | Passing a name whose directory already exists reopens that worktree rather than creating a second one. Two practical details catch people early: - **Workspace trust**: an interactive `--worktree` run in a directory you have never trusted exits with an error asking you to run `claude` there once and accept the trust dialog. Non-interactive runs with `-p` skip that check. - **Untracked noise**: the worktrees live inside the repository, so add `.claude/worktrees/` to `.gitignore`. The worktree is a **fresh checkout**: gitignored files such as `.env` and installed dependencies are not there until you copy, link or install them. ## How Claude Code keeps the session inside its worktree Isolation is enforced by the harness, not left to the model. While a session is isolated in a worktree, Claude Code refuses tool calls that would touch the main checkout: 1. **File edits**: an `Edit`, `Write` or `NotebookEdit` aimed at a path in the main checkout is blocked. 2. **Command working directory**: a Bash command whose working directory resolves to the main checkout, or cannot be verified to stay outside it, is blocked. 3. **Git redirects**: `git -C`, `--git-dir`, `GIT_DIR`, `GIT_WORK_TREE` or a `cd` that points git back at the main checkout is blocked. 4. **Command shape**: a command whose git usage cannot be verified from its text, such as a computed command name, is blocked; this check cannot be turned off. Claude sees each refusal as a tool error naming the worktree, and the same checks cover every subagent the isolated session spawns. ## What the sessions still share - **The `.git` directory**: commits made in either session land in the same repository, so branches are visible from both. - **Project-scope plugins** installed from the main checkout. - **"Don't ask again" Bash approvals**, which are saved to the main checkout's `.claude/settings.local.json` in the usual case. - **Untracked skills and agents**: when the worktree has no `.claude/skills` of its own, the main checkout's project skills load there. ## Cleaning up when you exit On exit from an interactive worktree session, Claude Code inspects the worktree for changed or untracked files, uncommitted work in submodules and new commits: - **Clean and unnamed**: the worktree and its branch are removed automatically. - **Clean but named**: you are asked first, so you can keep it. - **Holding work**: you choose keep or remove; keeping prints a `claude --worktree <name> --resume` command for later, while removing deletes the directory, the branch and the work in them. - **State unverifiable**: you are prompted rather than having it removed silently. Runs with `-p` have no exit prompt, so their worktrees are never cleaned up automatically; remove them with `git worktree remove`, unlocking first if git reports a lock. ## The same isolation for subagents The flag isolates a whole session. To isolate a subagent inside a session instead, a custom subagent can declare `isolation: worktree`; it then gets a temporary worktree from the same base-branch rule, removed automatically when the subagent finishes without changes. Choose the session flag when you, not Claude, are running the parallel work.

  • What happens to the worktree of a `claude -p --worktree` run when the job ends?
    Nothing automatic. Non-interactive runs have no exit prompt, so Claude Code does not clean up their worktrees, and the lock it took on each at creation stays until a later session's stale-lock sweep releases it. Remove the worktree yourself with `git worktree remove`, running `git worktree unlock` first if git refuses because it is locked.
  • You kept a worktree with unfinished work on exit. How do you continue in it tomorrow?
    Run the `claude --worktree <name> --resume` command Claude Code printed on exit. Passing `--worktree` a name whose directory already exists opens that worktree instead of creating a new one, and the resume returns the conversation to it after Claude Code checks it is still a separate checkout.
  • Does a session started with `--worktree` protect your main checkout from a subagent it spawns?
    Yes. The isolation checks apply to the session and to every subagent it spawns, whether or not that subagent declares `isolation: worktree`. A subagent edit or git command that targets the main checkout fails with a tool error, just as it would from the session itself.

  • Two sessions in one checkout are safe because Claude Code locks the files it edits.
  • A --worktree session starts from my current branch with my unpushed commits.
  • The --worktree flag copies .env and other gitignored files in automatically.
  • Exiting a worktree session always deletes the worktree and its branch.
  • Each worktree is a separate clone, so its commits never reach the main repository.