Git worktrees for coding agents: run several agents on one repo without collisions.

Start a second coding agent in the same checkout as the first one and you will meet the same wall every time: two processes, one working tree. One agent switches a branch, and files change under the other. Both run the tests, and the results describe a codebase neither of them wrote. Something gets lost, and it is usually your afternoon.

The fix is older than the agents. Git has had isolated checkouts for a decade. One worktree per agent is the convention every serious agent workspace settled on, and you can set it up today with the git you already have.

What a git worktree is

A worktree is a second checkout of the same repository, in a different directory, on a different branch, sharing one object database. Creating one is cheap: git copies no history, hard-links or symlinks what it can, and checks out a branch.

git worktree add ../leon-audit -b task/audit-auth
# a new directory, on a new branch, sharing this repo

git worktree list
# /code/leon          abc1234 [main]
# /code/leon-audit    abc1234 [task/audit-auth]

git worktree remove ../leon-audit
git worktree prune   # clean up records for directories you deleted

The mental model: a branch is a line of history, a checkout is where that line is materialized on disk. Worktrees let you materialize several branches at once. That is all agents ever needed.

One worktree per task

Name the directory after the task, not the agent, and branch from the same base. Then follow one rule for the whole task: nothing edits the main checkout. Not you, not the agent, not a quick hotfix.

1. Create a worktree and branch for the task: git worktree add ../app-search -b task/search-filters.
2. Start the agent inside that directory. It now sees the branch, the files and the lock state the task owns.
3. Let it work, and edit the same task with your own hands in the same directory if you want. You and the agent share one checkout of it, which is what makes pairing work.
4. Review, run the tests, commit, push, open the pull request. Merge to main as usual.
5. Remove the worktree once the branch is merged. git worktree prune sweeps the records.

Worktrees with the agents you run

Some agents create worktrees themselves. For every other agent, a worktree is just the directory you start it in, so the same pattern works everywhere.

• Claude Code has built-in support: start it with claude --worktree, or turn on worktrees in the desktop app, which puts each new session in its own checkout under .claude/worktrees. You can share untracked files you want present, such as .env, through a .worktreeinclude file.
• Cursor ships worktree flows through /worktree and --worktree, and its cloud agents work on their own clone.
• Codex, opencode and the rest of the terminal agents do not manage checkouts. They run where you point them, which is exactly the argument for handing each one its own worktree first.
• Any agent, any terminal. If a tool is a CLI, cd ../app-search && agent is the entire integration.

The sharp edges

Worktrees solve file collisions completely and create three smaller problems, all manageable:

• Disk and dependencies. Each worktree is a fresh checkout, so node_modules is not there by default. Two options: reinstall per worktree, or share one install by symlinking (ln -s ../../app/node_modules node_modules) or with an APFS clone on macOS. Sharing is faster and mostly fine; reinstall when dependency drift bites.
• Ports collide. Two dev servers on two worktrees both want port 3000. Give each task a port, or read the port from an env file per worktree. Agents rarely notice this until something answers on the wrong server.
• Untracked files stay behind. .env, local databases, certificates. Copy or symlink what a task needs, or use the .worktreeinclude convention where your agent supports it.
• Cleanup is real. Six worktrees from last week become six confusing checkouts. Remove them when branches merge. git worktree prune is idempotent and safe.

What a workspace adds on top

Worktrees are the mechanism, not the interface. Once you run four agents on three repos, you are doing fleet management with git commands and terminal tabs, and that is the part people hand to an ADE.

Leon turns the mechanics into a tree: every session grouped under its project and worktree, with the branch, the agent, a status light and the usage in the footer. Sessions resume where they were, without duplicates. History for Claude Code, Codex and opencode is searchable in milliseconds, so the worktree you finished last week is one search away instead of one archaeology dig.

Nothing about that tree hides git. The worktrees are real worktrees in real paths. You can open the same repo in your editor, run git worktree list and see exactly what the workspace sees. Download Leon if you want to look at the pattern from the GUI side, or keep doing it with git alone, which works fine up to a point.