# Claude Code worktrees: how to run coding agents in parallel > Run Claude Code agents in parallel with git worktrees: the --worktree flag, the desktop app's Worktree mode, Codex worktrees, setup gotchas and cleanup. - Tools: Claude, Conductor - Author: [Sandeep Panda](https://buildful.ai/authors/sandeep) - Published: 2026-11-09 - Compare: [Buildful vs Claude Code](https://buildful.ai/compare/claude-code) - Sources: - https://git-scm.com/docs/git-worktree - https://code.claude.com/docs/en/worktrees - https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md - https://code.claude.com/docs/en/desktop - https://learn.chatgpt.com/docs/environments/git-worktrees - https://code.claude.com/docs/en/agent-teams - https://code.claude.com/docs/en/claude-code-on-the-web - https://learn.chatgpt.com/docs/cloud --- Claude Code runs agents in parallel with git worktrees. Each session gets its own checkout and branch, so their edits don't collide. Start one with `claude --worktree ` (or `-w`), then run the same command with another name in a second terminal. The desktop app and OpenAI's Codex have worktree modes too. ## What is a git worktree? A git worktree is a second working copy of the same repo, checked out to its own folder on its own branch. Every worktree shares one `.git` history, so they're cheap to make. Git won't check out one branch in two worktrees at once, which is what keeps parallel agents apart. The [git docs](https://git-scm.com/docs/git-worktree) cover `git worktree add`, `list`, `remove` and `prune`. ## How do I run Claude Code in a worktree? Pass `--worktree` with a name. From Claude Code's [worktrees docs](https://code.claude.com/docs/en/worktrees): ```bash claude --worktree feature-auth claude -w bugfix-checkout ``` - **Where it goes:** `.claude/worktrees//` at your repo root, on a new branch called `worktree-`. Leave out the name and Claude Code picks one. - **What it branches from:** your remote's default branch. Set `worktree.baseRef` to `"head"` to branch from your local HEAD instead. - **A pull request:** `claude --worktree "#1234"` checks out that PR into `.claude/worktrees/pr-1234`. - **More agents:** run the command again in another terminal with a different name. Each one is its own session. The flag arrived in Claude Code 2.1.49, according to its [changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md). Add `.claude/worktrees/` to your `.gitignore`, as the docs suggest. ## What do I need to set up in each worktree? A worktree is a fresh checkout. That has three consequences: - **Install dependencies again.** Run `npm install` or your equivalent inside each worktree. - **Your `.env` isn't there.** Gitignored files aren't copied. List them in a `.worktreeinclude` file, in `.gitignore` syntax, and Claude Code copies them in. - **The repo needs at least one commit** before a worktree can branch from it. Two agents can still clash outside git. If both start a dev server on port 3000, one fails, so give each worktree its own port. ## How do I clean up Claude Code worktrees? When you leave an interactive session: - **No changes, no name:** Claude Code removes the worktree and its branch. - **Named, or with changes or commits:** it asks whether to keep it. If you keep it, it prints `claude --worktree --resume` to come back later. - **Non-interactive runs** (`claude -p`): nothing is cleaned up. Remove them yourself with `git worktree remove`. ## Can I create the worktrees myself? Yes. Plain git works, and you start Claude Code inside each folder: ```bash git worktree add ../project-feature-a -b feature-a cd ../project-feature-a && claude git worktree list git worktree remove ../project-feature-a ``` ## Does the Claude Code desktop app use worktrees? Only when you turn it on. The [desktop app](https://code.claude.com/docs/en/desktop) runs several sessions side by side in its sidebar, and **Worktree** is off by default. Switch it on and each session gets its own worktree in `/.claude/worktrees/`, with an optional branch prefix. A worktree left on disk is removed about 30 days after its session is archived or last opened, whichever is later. Commit untracked files you want to keep, since the app can delete them. The app runs on macOS and Windows, with Linux in beta. ## How do Codex worktrees work? The Codex app has a **Worktree** option under the composer. Codex creates the worktree in `$CODEX_HOME/worktrees` in detached HEAD, and **Create branch here** turns it into a branch you name. **Hand off** moves a chat between your local checkout and a background worktree. Codex keeps the 15 most recent worktrees and snapshots each one before deleting it. Details are in [Codex's worktree docs](https://learn.chatgpt.com/docs/environments/git-worktrees). In the Codex CLI, `--worktree` starts a session in a new managed worktree, as in `codex exec --worktree "implement the next step"`. It's been on by default since 0.156.0, released September 22, 2026. ## Worktrees, subagents and agent teams | | What it isolates | When to use it | |---|---|---| | Worktrees | Files and branches: each session edits its own checkout | Several separate tasks at once | | Subagents | Context: helpers work inside one session | Splitting one task into parts | | Agent teams | Nothing on disk: sessions share files and coordinate through a task list | Experimental, off by default; two teammates editing one file overwrite each other | Subagents can use worktrees too: set `isolation: worktree` in an agent's front matter. The [agent teams docs](https://code.claude.com/docs/en/agent-teams) cover the rest. ## Worktrees on your laptop or agents in the cloud? Worktrees run on your machine, so your laptop has to stay on and every agent shares its CPU, memory and ports. Apps like Conductor wrapped this workflow in a Mac app. Meta bought Conductor in November 2026, and [its cloud shuts down on November 20](https://buildful.ai/knowledge-base/conductor-shutdown). [Conductor alternatives](https://buildful.ai/knowledge-base/conductor-alternatives) lists the desktop apps that still do this, and [Conductor vs Claude Code](https://buildful.ai/knowledge-base/conductor-vs-claude-code) shows how much Claude Code now does on its own. Cloud agents skip worktrees. Each task gets its own machine: - **Claude Code on the web:** each `claude --cloud "..."` command starts its own cloud session. They share your plan's rate limits, so parallel sessions use them up faster ([docs](https://code.claude.com/docs/en/claude-code-on-the-web)). - **Codex cloud:** each task gets its own workspace and keeps working while your computer sleeps ([docs](https://learn.chatgpt.com/docs/cloud)). - **Buildful:** each task gets its own private cloud sandbox and ends in a pull request. ## Where Buildful fits Buildful runs tasks in parallel without worktrees. Each task gets a fresh clone in its own cloud sandbox, with your repo's setup commands and environment variables, so there's nothing to install again and no ports to share. It runs your checks, tests UI changes in a real browser and records it, and opens a pull request on GitHub. Smart Mode picks the right open-weight model for each task. On Pro and Team, you can also pick a frontier model like Claude or GPT, with prepaid credit or your own API key. Pro is $10 a month for 1,000 tasks, and Team is $40 for 3,000 shared by the team ([pricing](https://buildful.ai/pricing)). [Buildful vs Claude Code](https://buildful.ai/compare/claude-code) and [Buildful vs Conductor](https://buildful.ai/compare/conductor) have the full comparisons. ## Frequently asked questions ### How do I run multiple Claude Code agents at once? Open a terminal per agent and run `claude --worktree ` in each, with a different name every time. Each session works in its own git worktree and branch, so their edits don't collide. ### What does claude --worktree do? It starts Claude Code in a new git worktree at `.claude/worktrees//`, on a branch called `worktree-`. When you exit, Claude Code removes it if nothing changed, or asks whether to keep it. ### Does a Claude Code worktree copy my .env file? No. A worktree is a fresh checkout, so gitignored files like `.env` are missing. List them in a `.worktreeinclude` file and Claude Code copies them in. ### How do I delete a Claude Code worktree? Exit the session and choose to remove it, or run `git worktree remove `. Worktrees from `claude -p` runs are never removed automatically. ### Can two worktrees use the same branch? No. Git refuses to check out a branch that another worktree already has, unless you force it. Give each agent its own branch. ### Do Claude Code and Codex worktrees work the same way? Mostly. Both give each session its own checkout. Claude Code puts worktrees in `.claude/worktrees/` on `worktree-` branches, and Codex puts them in `$CODEX_HOME/worktrees` in detached HEAD until you create a branch. --- Source: https://buildful.ai/knowledge-base/claude-code-worktrees