--- title: "Git worktrees for parallel AI coding agents: setup and limits · Cork" description: "Set up git worktrees for parallel AI coding agents like Claude Code and Codex: exact commands, environment setup, cleanup, and what worktrees do not solve." canonical: "https://corkcli.com/blog/git-worktrees-parallel-ai-coding-agents" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # Git worktrees for parallel AI coding agents: setup and limits Set up git worktrees for parallel AI coding agents like Claude Code and Codex: exact commands, environment setup, cleanup, and what worktrees do not solve. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 6 min read Git worktrees let you check out several branches of one repository into separate folders at once, so each AI coding agent gets its own files and its own branch while sharing a single history. Create one per agent with `git worktree add ../repo-agent-a -b agent-a` (or `claude --worktree agent-a` in Claude Code), set up its environment, run the agent there, and remove it when the branch lands. Worktrees stop agents from overwriting each other while they work. They do not stop conflicts at merge time, and they do not tell one agent what another changed. ## How worktrees work The git docs describe `git worktree` as a way to "manage multiple working trees attached to the same repository," allowing you "to check out more than one branch at a time." Your original checkout is the main worktree; the others are linked worktrees. What is shared and what is not matters for agents: - **Shared:** the object store, all refs under `refs/` (branches and tags), and the repository config. A commit made in one worktree is immediately visible to the others as a branch. - **Per worktree:** `HEAD`, the index (staging area), and the files on disk. Two agents staging and committing in different worktrees do not interfere. By default `git worktree add` refuses to check out a branch that another worktree already has checked out, which is the protection you want: two agents cannot sit on the same branch by accident. ## Setup with plain git These commands are plain git, so they work with any agent you start from a terminal: ```bash # from the main checkout git worktree add ../myapp-search -b agent/search git worktree add ../myapp-billing -b agent/billing cd ../myapp-search && ``` Manage them with: ```bash git worktree list # see all worktrees and their branches git worktree remove ../myapp-search # delete one (add --force if it has changes) git worktree prune # clean up records of deleted folders git worktree lock ../myapp-billing # protect one from pruning or removal ``` Put worktrees outside the repository directory, or add their folder to `.gitignore`, so they do not appear as untracked files in the main checkout. ## Setup with Claude Code As of October 2026, Claude Code manages worktrees itself: ```bash claude --worktree search claude --worktree "#1234" # branch from pull request 1234 ``` This creates `.claude/worktrees/search/` on a new branch `worktree-search`, branched from your default branch on the remote. Set `worktree.baseRef` to `"head"` in settings to branch from your current local `HEAD` instead. Useful details: - **Subagents:** add `isolation: worktree` to a subagent's frontmatter so each run gets a temporary worktree, removed automatically if it made no changes. - **Enforcement:** while isolated, Claude Code blocks edits and git commands aimed at the main checkout. - **Cleanup:** on exit, a clean unnamed worktree is removed; one with changes or commits prompts you to keep or remove it. The Codex app also offers worktrees, and OpenAI's guidance for parallel chats is to "avoid letting two chats change the same files." ## Set up the environment in each worktree A worktree contains only tracked files. Claude Code's docs say it directly: "A worktree is a fresh checkout, so initialize your development environment there." Budget for: - **Dependencies.** Each worktree needs its own `node_modules`, virtualenv or build output. Run your install step in each one, or script it. - **Gitignored config.** `.env` and local secrets are missing. In Claude Code, list them in a `.worktreeinclude` file (gitignore syntax) and they are copied into each new worktree: ```text .env .env.local config/secrets.json ``` - **Ports and services.** Two agents starting the dev server on port 3000 will clash. Give each worktree its own port through its `.env`. - **Git LFS.** If you set up LFS with `git lfs install --local`, worktrees Claude Code creates contain pointer files; run `git lfs pull` inside the worktree. - **Disk.** Each worktree is a full copy of the working files plus its own dependencies. ## The limits of worktrees Worktrees solve one problem well: no agent can overwrite another agent's uncommitted files. Know what they leave open. 1. **Conflicts move to merge time.** Two agents that edit the same file in different worktrees will conflict when the second branch merges. Worktrees postpone the collision; they do not prevent it. 2. **Semantic conflicts merge cleanly.** If one agent renames `getUser` to `fetchUser` and another adds a new call to `getUser` in a different file, git merges both without complaint and the build breaks. Only a compile, type check or test run on the merged result catches it. 3. **Agents are blind to each other.** An agent in one worktree has no idea what the others are doing until their work lands. Claude Code's cross-session messaging lets Claude tell other sessions "what landed," but it is plain text sent when Claude decides to. 4. **Setup cost scales with agents.** Ten agents means ten installs and ten copies of the working files. 5. **Submodules are a weak spot.** The git docs warn that "the support for submodules is incomplete" and that it is "NOT recommended to make multiple checkouts of a superproject." The practical answer to limits 1 and 2 is to land one branch at a time: rebase onto the latest main, run the full test suite, then push, and have every later branch rebase onto what landed. ## How Cork helps Worktrees isolate files. Cork coordinates the agents in them, or lets agents share one checkout when a worktree per agent is too expensive. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. Against the limits above: - **Live awareness and [semantic lint](https://corkcli.com/blog/semantic-lint) (limits 2 and 3):** when an agent in one worktree renames a function or changes a signature, agents that depend on it hear it on their next step, and the change becomes a lint rule they are checked against. - **[Write gate](https://corkcli.com/blog/write-gate) (limit 4):** an edit against code another agent is changing right now is held until your agent has their version, which makes a shared checkout workable. - **Landing (limit 1):** `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes. - **Briefing:** a fresh worktree starts with no context; Cork hands each agent the signatures, callers and recent changes of the code it is about to touch. Cork Free covers one machine with no account; the paid plan adds teammates' machines. Install: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` For a side-by-side comparison, see https://corkcli.com/blog/cork-vs-git-worktrees. ## Frequently asked questions ### Can two worktrees use the same branch? Not by default. `git worktree add` refuses a branch that is already checked out elsewhere unless you pass `--force`, and forcing it defeats the point. ### Do git worktrees prevent merge conflicts? No. They prevent overwrites while agents work. Conflicts appear when branches merge, and semantic conflicts can merge cleanly and still break the build. ### How do I delete a worktree? Run `git worktree remove `, adding `--force` if it has uncommitted changes. If a worktree is locked, run `git worktree unlock ` first. `git worktree prune` cleans up records for folders you already deleted. ### How many worktrees can I run at once? The git docs do not list a limit; the practical limits are disk space, install time and how many branches you can review and merge. ## Sources - - - - - ## Related reading - [Cork Free: set up multiplayer coding agents on one machine in one command](https://corkcli.com/blog/cork-free-setup-one-machine): Set up Cork Free in one command so Claude Code, Codex and Cursor agents on one machine stop overwriting each other. No account; data stays on the machine. - [How to add a remote MCP server to Claude Code, Codex, Cursor and Gemini CLI](https://corkcli.com/blog/add-remote-mcp-server-claude-code-codex-cursor-gemini-cli): Exact, verified commands and config to add a remote HTTP MCP server to Claude Code, Codex, Cursor and Gemini CLI, with scopes, auth headers and OAuth sign-in. - [Pre-commit checks for code written by AI agents](https://corkcli.com/blog/pre-commit-checks-ai-generated-code): Pre-commit checks for AI-written code: git hooks, the pre-commit framework, secret scanning, and agent hooks in Claude Code, Codex and Cursor. - [Cork vs Crystal: parallel sessions in worktrees, or agents that know about each other](https://corkcli.com/blog/cork-vs-crystal): Cork vs Crystal: Crystal ran parallel Claude Code and Codex sessions in worktrees and is now deprecated. Cork coordinates parallel agents on shared code. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/git-worktrees-parallel-ai-coding-agents