What are git worktrees? Claude Code, Codex, Cursor, Grok

A git worktree is a second working directory for the same repository. It has its own files and its own checked-out commit. It shares the commit history with your main checkout. Coding agents use that so two tasks can edit at once without writing the same folder.

Git worktrees is the post that owns the Git commands: git worktree add, git worktree list, and git worktree remove. This entry is how Claude Code, Codex, Cursor and Grok Build create one for you.

How a worktree works

Git stores one object database per repository. A worktree is another checkout pointing at that database. You can have your branch open in one directory and an agent on a different commit in another.

Git will not check out the same branch in two worktrees. A branch is one movable pointer. Two directories moving it would race. Agents that want several checkouts either use a detached HEAD or a new branch per checkout.

Ignored files do not come along with a fresh checkout. .env stays in the directory where you created it, unless the tool copies it.

Git worktrees in each tool

Claude Code

claude --worktree feature-auth creates a worktree under .claude/worktrees/ and starts the session there, on a branch named worktree-feature-auth. An interactive start in a directory you have not trusted yet stops and asks you to run claude there once. claude -p --worktree skips that trust check.

You can also ask Claude to work in a worktree during a session. It calls EnterWorktree. A move outside .claude/worktrees/ asks you first. If permissions.blockWritesOutsideWorkingDirectories is on, Claude Code removes EnterWorktree and ExitWorktree. Start with --worktree in that case, or turn the key off and restart.

A subagent can take isolation: worktree in its frontmatter. That subagent gets its own worktree. Claude Code removes it when the subagent finishes with no changes. A worktree with changes stays until a later sweep can remove it without losing work.

.worktreeinclude in the repo root lists gitignored paths to copy into each new worktree. See Run parallel sessions with worktrees.

OpenAI Codex

In the ChatGPT desktop app, pick Worktree under the composer, pick the starting branch, and send the prompt. Codex creates a managed worktree in a detached HEAD state. The default directory is $CODEX_HOME/worktrees. Settings, then Worktrees, changes that root.

Handoff moves a chat between your local checkout and that worktree. Git still allows the branch in only one place, so handing off is how you bring the same branch into the checkout you already use. Create branch here turns the detached worktree into a branch you can push.

The CLI command is /worktree. For a script, codex exec --worktree creates a managed worktree. That flag needs a local run. It does not combine with resume, review, --ephemeral, or --ignore-user-config.

Codex keeps the 15 newest managed worktrees and can delete older ones. A pinned chat and a chat still in progress are left alone. Archiving the chat deletes its managed worktree. A snapshot is saved first, and reopening the chat can restore it.

.worktreeinclude copies ignored files into a local managed worktree. Codex also copies an ignored AGENTS.override.md without listing it. See Worktrees.

Cursor

The Agents Window can start an agent in a worktree, or move one there. The agent keeps editing that checkout. You review it in the Agents Window, commit from it, or bring the result back to the main workspace.

In the IDE, /worktree runs the rest of that chat in a separate checkout. /apply-worktree brings the changes into the main checkout. /delete-worktree removes the isolated one. /best-of-n runs the same task on more than one model, each in its own worktree, and does not merge a winner for you.

.cursor/worktrees.json holds setup commands. Cursor reads it when it creates a worktree from the Agents Window, the IDE, or the CLI. setup-worktree is the generic list. setup-worktree-unix and setup-worktree-windows override it. $ROOT_WORKTREE_PATH is the main checkout, so a setup command can copy .env from there.

The default cap is 25 worktrees per machine, across workspaces, set with cursor.worktreeMaxCount. The settings example checks every 6 hours with cursor.worktreeCleanupIntervalHours. Worktrees you made with git worktree add count toward that cap. See Worktrees.

Grok Build

grok -w starts a worktree session. grok --worktree=feat "refactor module X" puts the name on the worktree and leaves the prompt out of it. grok -w --ref main starts from a clean checkout of that ref. Without --ref, the worktree starts at your current HEAD, uncommitted changes included, detached.

In the TUI, /fork --worktree forks the current session into a worktree. Ctrl+W on the welcome screen opens the New Worktree dialog. Ending a session does not delete the worktree.

grok worktree list shows them. grok worktree rm removes the ones you name. grok worktree gc drops entries whose directory is already gone, and grok worktree gc --max-age 7d also expires idle worktrees that no process is using. See Worktrees.

Details checked against each vendor’s documentation in November 2026.

A real example

Two tasks on this site at once: you keep the homepage checkout, and an agent changes the RSS feed in another directory.

Claude Code, from the repo:

claude --worktree rss-limit

A subagent that should always do that kind of edit in its own worktree, saved as .claude/agents/rss-limit.md:

---
name: rss-limit
description: Changes the RSS item limit and runs the tests
isolation: worktree
---

Change the RSS item limit in src/pages/rss.xml.ts from 30 to 20. Run npm run build. Report the files you changed.

Cursor’s setup file, so the new checkout can install and see the same env file, is .cursor/worktrees.json:

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Codex and Claude Code copy ignored paths listed in .worktreeinclude instead. One line per path, in the repo root:

.env
.env.local

Grok Build’s matching start is grok -w --ref main "change the RSS item limit to 20 and run npm run build".

When to use a worktree

Use one when two edits would collide in one working tree. A feature in progress, plus a small fix an agent can land on its own, is the usual case. Parallel coding agents is the review problem that shows up after the directories exist.

Skip it for a one-line change on the branch you already have open. A second checkout means a second node_modules, and Git will refuse to check that same branch out in both places.

Subagents are the other split. They isolate context inside one session. A worktree isolates files. Claude’s worktrees page says you can use both.

Pitfalls

The branch error is Git, not the agent. Codex quotes it: fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'. Hand the chat back, or check out a different branch in one of the two directories. Creating the branch in both places does not work.

A fresh worktree has no .env until you copy it. Claude Code and Codex read .worktreeinclude. Cursor runs the commands in .cursor/worktrees.json. Grok’s worktrees page does not document a copy list.

Claude Code hooks do not follow the directory. ${CLAUDE_PROJECT_DIR} stays at the project root where the session started. The hook’s cwd is the worktree. A hook that assumes those two paths are the same reads the main checkout.

Grok leaves the directory in place when the session ends. Claude prompts before it deletes a worktree that has work. Cursor can delete older worktrees, including ones you created with git worktree add, once the machine is over its cap. git worktree list is the check before you assume a directory is still there.

Related on flaviocopes.com

• Git worktrees is the git worktree command itself, and the reason a second checkout beats stashing.
• Parallel coding agents is what you do with the diffs once several checkouts exist.
• A deep dive into T3 Code starts a thread in the current checkout or in a new worktree.
• Herdr can create the worktree and the agent for you.
• Several finished tasks are hard to remember from the directories alone. Work Tracebook stores the reports the agents write, and the timeline tutorial is the setup.

Related glossary entries

• Subagents: A subagent is a helper your coding agent starts with its own context window. How subagents work in Claude Code, Codex, Cursor and Grok Build.
• Sessions: A session is a saved coding-agent conversation you can resume later. How Claude Code, Codex, the Cursor CLI and Grok Build store, name, resume and fork one.
• Cloud agents: Cloud agents run a coding task on a remote machine instead of your laptop. How Claude Code, Codex, Cursor and Grok Bot start one, and what they cannot see.
• Sandbox: An agent sandbox limits which files and hosts a coding agent's commands can reach. How the boundary works in Claude Code, Codex, Cursor and Grok Build.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.