Issue 00 · Autumn 2026日本語 · RSS
AgentKoji

Run Parallel AI Agents with Git Worktrees

claude --worktree gives each Claude Code session its own git worktree under .claude/worktrees/. How to run agents in parallel on one repo and clean up after.

TL;DR

  • To run two Claude Code sessions on one repository at once, give each its own directory and branch with git worktree.
  • A branch can be checked out in only one worktree at a time, and git worktree remove refuses while modified or untracked files remain; use git worktree prune after deleting with rm.
  • Claude Code's --worktree flag creates a worktree under .claude/worktrees/<name>/ on a branch named worktree-<name>; add that directory to .gitignore.

To run two Claude Code sessions on the same repository at once, give each one its own working directory. The tool for that is git worktree. This guide covers the basic git worktree commands, Claude Code’s --worktree flag, what each worktree needs before an agent can work in it, how to decide how many to run, and how to clean up. For what goes wrong when you run agents in parallel, see Subagent Failures in Parallel Runs.

Why separate working directories

Two agents in one working tree step on each other’s edits. One may run the tests halfway through the other’s change. A branch switch or a git stash drags the other agent’s work along with it.

With worktrees, each agent gets its own directory and its own branch. History and remotes are shared, so it’s lighter than a second clone.

Git worktree basics

We ran these in a throwaway repository on 2026-10-23, with:

git version 2.54.0 (Apple Git-157)

Create a worktree on a new branch, feature/login:

cd todo-app
git worktree add ../todo-app-login -b feature/login
Preparing worktree (new branch 'feature/login')
HEAD is now at bdb60cd init

List worktrees with git worktree list. We shortened the paths:

/tmp/todo-app       bdb60cd [main]
/tmp/todo-app-login bdb60cd [feature/login]

A branch can be checked out in only one worktree at a time. Try a second worktree on the same branch and git stops you:

fatal: 'feature/login' is already used by worktree at '/tmp/todo-app-login'

git worktree remove refuses while untracked or modified files remain:

fatal: '../todo-app-login' contains modified or untracked files, use --force to delete it

If you delete a worktree directory with rm instead, clean up the leftover admin files with git worktree prune. Here we made a worktree, deleted it with rm, then pruned:

$ git worktree add ../todo-app-tmp -b tmp
Preparing worktree (new branch 'tmp')
HEAD is now at bdb60cd init
$ rm -rf ../todo-app-tmp
$ git worktree prune -v
Removing worktrees/todo-app-tmp: gitdir file points to non-existent location

Source: https://git-scm.com/docs/git-worktree (checked 2026-10-23)

Claude Code’s —worktree

Claude Code has a flag that creates a worktree and starts the session inside it. We confirmed it in claude --help on 2.1.309:

  -w, --worktree [name]                 Create a new git worktree for this
                                        session (optionally specify a name)
claude --worktree feature-auth

The worktree goes under .claude/worktrees/<name>/ at the repository root, on a new branch named worktree-<name>. Run the command again in another terminal with a different name to start a second session. The docs suggest adding .claude/worktrees/ to .gitignore.

By default, new worktrees branch from the repository’s default branch, usually main. To branch from your current work instead, set worktree.baseRef to "head" in settings. To start from a specific existing branch, create the worktree with git directly.

Source: https://code.claude.com/docs/en/worktrees (checked 2026-10-23)

We didn’t start a Claude Code session in a worktree for this article (not run).

What each worktree needs

A worktree is a fresh checkout. Dependencies such as node_modules aren’t there, so install them in each worktree. Gitignored files such as .env aren’t there either. In Claude Code, a .worktreeinclude file at the project root copies matching files into each new worktree. It uses .gitignore syntax:

.env
.env.local

Only files that match a pattern and are also gitignored get copied.

Source: https://code.claude.com/docs/en/worktrees (checked 2026-10-23)

Keep secrets in agent working directories to a minimum; see Keep Secrets Away from Claude Code. Dev-server ports and local databases are shared across worktrees, so give each worktree its own port if they run at the same time.

How many to run

On a subscription plan, usage is shared across all your sessions. There is a five-hour session limit and a weekly limit, and more sessions reach them sooner. See When You Hit Claude Code’s Usage Limit.

Source: https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan (checked 2026-10-23)

The costs page says agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, and recommends keeping teams small. The /usage breakdown shows what share of recent usage went to skills, subagents, plugins and MCP servers. Those figures come from session history on that machine, so other devices and claude.ai aren’t included.

Source: https://code.claude.com/docs/en/costs (checked 2026-10-23)

We found no official number for the maximum you should run in parallel (unverified).

Running in parallel on a server

If the work has to keep going after you close your laptop, run it on an always-on server. Parallel sessions use memory and CPU at the same time, so size the server to the number of sessions, and check free disk space, since each worktree gets its own dependencies. Use tmux or similar so sessions survive a disconnect. For the setup, see Run an AI Agent 24/7 on a VPS.

Cleaning up

When you exit an interactive --worktree session, Claude Code checks the worktree:

Non-interactive -p runs have no exit prompt, so their worktrees stay. Remove them with git worktree remove; if git refuses because the worktree is locked, run git worktree unlock first.

Source: https://code.claude.com/docs/en/worktrees (checked 2026-10-23)

Summary