What are Git worktrees?
Git worktrees are extra working directories for one repository: each has its own files, index and checked-out branch or commit, and all of them share one .git history. Parallel agents each get one, so their edits, installs and tests never touch the same files. Claude Code starts one with --worktree, Codex with --worktree or /worktree, and Cursor documents Worktrees as isolated Git checkouts.
- In Polish
- Git worktrees
- First set up at
- Level 3, free guide
- Also searched as
- worktree, git worktree
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Why it matters.
Three agents in one checkout collide silently: one agent’s formatter rewrites a file another is editing, a dev server takes the next free port, and tests pass against a neighbour’s server. A worktree per agent separates the files. It does not separate ports, databases, secrets or deploys, so a worktree is not a sandbox.
One checkout, or one each
Three agents on three tasks: in one directory, and in a worktree each.
- Shared between agents
- Separated by Git
- What you can rely on
One checkout Shared
-
The setup
Three agents, one directory
Three terminals open on the same checkout.
-
The collision
A formatter rewrites a file another agent is editing
The second agent’s dev server quietly takes the next free port.
-
The tests
Pass against a neighbour’s server
The third agent’s end-to-end tests run against the second agent’s server.
-
What you can rely on
Not which code was tested
Each report says “done”. None proves which code was tested.
One worktree each Files isolated
-
The setup
--worktreefor each agentEach agent gets its own directory, and every worktree shares one
.githistory. -
The files
Own working files and index
Edits, installs and tests never touch another agent’s files.
-
Still shared
Ports, databases, secrets, deploys
A server can still fall back to a neighbour’s port: give each stream a port block and its own local state.
-
What you can rely on
Files cannot collide
Worktrees isolate files, not ports, databases, caches or a shared dev server.
How each tool does it.
Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.
Cursor
Worktrees “let Agent work in isolated Git checkouts”, and you run and watch parallel agents from the Agents Window. Current setup steps were not re-verified.
Level 3 guide (Cursor docs), 2026-08-28
Claude Code
claude --worktree NAME (-w) creates .claude/worktrees/NAME/ on a new branch worktree-NAME.
It branches from the remote default branch unless worktree.baseRef is "head". List development files in a .worktreeinclude: Claude Code copies only files that match it and are gitignored. A clean worktree of an unnamed session is removed on exit, while headless claude -p --worktree runs leave theirs behind.
Worktrees guide, Claude Code 2.1.283, 2026-09-26
Codex
codex --worktree or /worktree starts a managed worktree under $CODEX_HOME/worktrees/ on a detached HEAD.
Worktree support is on by default since 0.156.0, but a session uses one only when you opt in. A managed worktree carries no uncommitted edits, untracked files or gitignored files, so create a branch before the agent commits: commits on a detached HEAD belong to no branch.
Codex worktrees guide, Codex 0.157.1, 2026-09-26
Questions about Git worktrees.
Why do AI agents need worktrees?
Parallel agents in one checkout overwrite one another: a formatter rewrites a file another agent is editing, and a dev server falls back to the next free port. A worktree gives each agent its own files, so Git enforces the isolation instead of everyone taking turns.
Is a worktree the same as a clone?
No. All worktrees of a repository share its .git directory: objects, refs and git config. Each has its own working files, index and checked-out branch. Because git config is shared, a config write in one worktree changes all of them.
What does a worktree not isolate?
Ports, local databases, caches and queues, git config, the permission approvals Claude Code saves, and production data, deploys and secrets. Gitignored files such as .env and node_modules/ are missing from a new worktree. Give each stream its own port block and local state.
Which tools start agents in worktrees?
Claude Code with claude --worktree, Codex with codex --worktree or /worktree, and Cursor, whose docs describe Worktrees as isolated Git checkouts. In Codex a managed worktree starts on a detached HEAD, so create a branch before the agent commits.
Keep reading.
The guides that go deeper, and the terms and comparisons next to this one.
Does this page answer your questions?
One tap, no sign-in.
What are you here for?
What is holding you back?
How does it read?
Thanks. If you left an email, Michał will reply.
Answering your questions?
One tap each. Close whenever you like.
no sign-in
Read the guides in the same words.
Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Michał replies, not a bot. The address is used for this reply only.