Guide
Claude Code worktrees, explained
Run several coding agents at once, each in its own git worktree, and review what each one produced without the sessions touching each other or your main checkout. The pattern, the commands, and how to read the result before you merge it.
Why agents get their own worktree
A coding agent edits files in whatever directory you point it at. Run two agents in the same checkout and they overwrite each other's work; run one agent in your main checkout and you can't touch the code until it finishes. Worktrees fix both. Each agent gets a real directory with its own checked-out branch, while all the worktrees share one repository underneath, so nothing is cloned twice and every commit lands in the same place. You keep working in your checkout, the agents work in theirs, and each one leaves a branch for you to review.
If worktrees themselves are new to you, start with git worktrees, explained. This guide is about the agent workflow built on top of them.
One worktree per agent
The pattern is one worktree, one branch, one agent. Create the worktree, point the agent at it, and let it work:
Name the directory after the task (repo-agent-navbar, not repo-2). When three sessions are running, the paths are how you tell them apart. Each worktree also needs its own node_modules or build directory, because untracked files are per-worktree; that isolation is what keeps one agent's build from breaking another's.
How each tool handles worktrees
Increasingly you don't create the worktree at all; the tool does:
| Tool | How it uses worktrees |
|---|---|
| Claude Code | isolation: worktree in subagent frontmatter runs each subagent in its own worktree |
| Cursor | Agents Window; /worktree runs an agent in a worktree |
| Codex app | Worktree under the composer; the worktree starts in detached HEAD, and Codex keeps the 15 most recent by default |
| opencode | Runs parallel sessions the same way |
Either way the end state is the same: a directory on disk, a branch with the agent's commits, and a human who has to decide whether to merge it.
Reviewing what an agent produced
When a session ends you have a branch and a directory. Read the whole change against the branch it started from, and use the three-dot form so you see only the agent's work even if main has moved on:
That gets you through the code. Where a terminal diff fails is everything else agents write: READMEs, specs, plans, and data files. A reworded paragraph in a line diff is a wall of red and green, and "Binary file differs" is no way to review an image. The variants and flags are covered in git diff, explained.
Merging and cleaning up
Once the branch passes review, merge it from your main checkout and retire the worktree:
remove refuses if the worktree still has uncommitted changes, which doubles as a last check that nothing the agent did was left behind. If the tool already deleted the directory itself, git worktree prune clears the leftover record.
A Codex app worktree starts in detached HEAD, so there is no branch to merge until you create one. Inside the worktree, run git switch -c agent-navbar, then merge that branch as shown.
Cheat sheet
| Task | Command |
|---|---|
| Worktree + branch for an agent | git worktree add -b branch ../dir main |
| List worktrees | git worktree list |
| Everything the agent changed | git diff main... |
| The agent's commits | git log --oneline main.. |
| Remove a worktree | git worktree remove ../dir |
| Remove, discarding local changes | git worktree remove --force ../dir |
| Clean up after manual deletion | git worktree prune |
The full command reference, including move, lock and the errors you'll hit, is in git worktrees, explained; git's own manual is git-worktree.
A window per agent, one command away
Meridian is a native Mac Git client built for agent review: every worktree gets its own titled window, mrd opens whichever one you're standing in, and Markdown, CSV and JSON diffs render as documents.
Free 14-day trial | One licence, three Macs
Related: git worktrees, explained | git diff, explained | Markdown diff viewer | Best Git client for Mac
Claude Code worktrees, answered
Does Claude Code use git worktrees?
Yes. Claude Code runs subagents in isolated worktrees via isolation: worktree in subagent frontmatter. Each subagent gets its own directory and branch, so parallel sessions never touch each other's files.
How do I review what Claude Code changed before committing?
git diff main...branch in the agent's worktree shows everything the agent changed since it branched off. For prose and data files, a rendered view helps: cd into the worktree, type mrd, and Meridian opens it in its own window with the change rendered as documents.
Can two agents work in the same worktree?
Not safely. A worktree is one directory with one checked-out branch. Two agents editing the same files overwrite each other's work. One worktree per agent is the pattern.
Do Cursor and Codex use worktrees too?
Yes. Cursor's Agents Window runs an agent in a worktree via /worktree. In the Codex app, choose Worktree under the composer and the chat runs in a worktree that Codex creates in $CODEX_HOME/worktrees. opencode runs parallel sessions the same way.
How do I open an agent's worktree in a Git GUI?
Most GUIs show worktrees as tabs inside one window. Meridian opens each worktree in its own titled window: cd into the directory, type mrd, and that window is just that agent's worktree.