Claude Code worktrees: run parallel sessions with --worktree, set them up, and clean them up

A git worktree is a second checkout of the same repository, on its own branch. claude --worktree <name> (or -w) creates one under .claude/worktrees/<name>/ on a new branch worktree-<name> and starts Claude Code in it, so two sessions can edit one repository without touching each other's files. Run it again with another name in another terminal for a third.

Start Claude Code in a worktree

Inside a session you can also ask Claude to "work in a worktree"; it creates one with its EnterWorktree tool.

• Trust first. An interactive --worktree run needs the folder trusted: run claude once in the repository and accept the dialog, or --worktree exits with an error. claude -p --worktree skips the check.
• Keep it out of git status. Add .claude/worktrees/ to .gitignore.
• A name that exists opens that worktree again instead of making a new one; with the default base, a clean one with no commits of its own restarts from the default branch.

Set up the worktree: .env and dependencies

A worktree holds only tracked files. Your .env, local config and installed dependencies are not there. For ignored files, add a .worktreeinclude at the project root, in .gitignore syntax:

.env
.env.local
config/secrets.json

Claude Code copies files that match a pattern and are gitignored into every worktree it creates with git: --worktree ones, subagent worktrees and the desktop app's parallel sessions. Dependencies you install in the worktree yourself, or ask Claude to.

Which branch a worktree starts from

• Fresh, the default ("fresh"): the remote's default branch, usually main. Claude Code fetches it first when the repository has not been fetched in 24 hours.
• Head ("head"): your current local HEAD, with unpushed commits — set "worktree": { "baseRef": "head" } in settings.
• A specific branch: worktree.baseRef does not take a branch name; make that worktree with git, below, and start claude in it.

Subagents in their own worktrees

Add isolation: worktree to a subagent's front matter in .claude/agents/, or ask Claude to "use worktrees for your agents". Each subagent then edits a temporary worktree from the same base branch; one that finishes without changes is removed at once. More on subagents: Claude Code subagents.

Clean up worktrees

When you exit an interactive worktree session, Claude Code checks it first:

• Clean, unnamed session: the worktree and its branch are removed.
• Clean, named session: it asks before removing.
• Changes, untracked files or new commits: it asks you to keep or remove. Keep it and it prints the claude --worktree <name> --resume command to come back.

Runs with -p get no exit prompt and are not cleaned up. Remove a worktree yourself with git worktree remove <path>, adding --force when it has uncommitted changes; if git says it is locked, run git worktree unlock on it first. Worktrees made for subagents and background sessions are swept once they are older than cleanupPeriodDays, unless they still hold work.

Worktrees by hand, with git

For a worktree outside the repository or on an existing branch, use git and start Claude in it:

What gets hard with several worktrees

Each worktree is a terminal of its own, a branch of its own and a diff to review of its own. With three or four running, you lose track of which one is waiting on you and which has finished, and every review starts with a cd and a git diff. Claude Code's agent view lists background sessions; sessions you started in other terminals are not in it.

Worktrees in the Caprock app

⤢

⤢

Caprock is a free desktop app for macOS, Windows and Linux that records every agent session on the machine, whether or not it started it, and runs Claude Code, Codex, OpenCode, Gemini CLI, Grok Build and Hermes Agent in terminal tabs, per project.

• Every session, whichever worktree it is in. The sidebar lists a project's agent sessions, each with the branch it works on when that is not the project's own: in worktrees claude --worktree made, ones you made with git, and Caprock's own.
• A new worktree with an agent in it. New agent → Where → New copy from a branch, and Caprock runs git worktree add into .caprock-worktrees/<name> on a new branch caprock/<name>, from the branch you pick (fetched from the remote first unless you untick it), and starts the agent there.
• Ready to run. The new worktree gets the ignored files your .worktreeinclude lists, the way claude --worktree does, and a project's setup command, such as npm install, runs in the agent's terminal before the agent starts.
• Several tries at once. Set Attempts to 2, 3 or 4 and the same agent gets the same first message in that many worktrees from one commit; Compare attempts shows each one's files and lines changed, cost so far and time.
• A task becomes a worktree. Type a task into the palette (⌘K) that matches nothing — "Fix the login bug" — and Enter opens New agent with it as the first message, in a new worktree named fix-the-login-bug.
• Review each one. Review and commit in a session's inspector, or Review changes in ⌘K, opens its worktree's Changes view: stage files or hunks, commit, push, and with GitHub connected open a pull request and follow its checks. Open in … opens the worktree in VS Code, Cursor, Zed or a JetBrains IDE.
• From the phone. A paired phone you let control sessions can make a worktree — on an existing branch, a new one or a branch only the remote has — and start an agent in it.

• Clean up. Clean up copies… in a project's menu lists every worktree with its branch, size on disk and whether it is merged, pushed or has uncommitted changes; it removes only the ones Caprock made, and asks again before anything unsaved is lost. A copy Caprock made that is merged, pushed and clean can go by itself: Settings → Worktrees offers Off, Ask (the default) or Auto.

Add .caprock-worktrees/ to .gitignore beside .claude/worktrees/. Install Caprock.

Claude Code's worktrees or Caprock's

• Claude Code's --worktree — one or two parallel sessions in terminals you already have, with cleanup on exit and .worktreeinclude.
• Subagents with isolation: worktree — parallel edits inside one session that report back to it.
• Caprock's app — several worktrees and agents across projects in one window, each with its diff a click away, whichever tool made the worktree, and several tries at one task compared by cost. More ways to run agents side by side: run Claude Code agents in parallel.