--- title: "How to run multiple Claude Code agents on one repo without conflicts · Cork" description: "Run several Claude Code agents on one repository safely: worktrees, subagents, agent teams, cross-session messaging, and a clean landing routine, step by step." canonical: "https://corkcli.com/blog/run-multiple-claude-code-agents-one-repo" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # How to run multiple Claude Code agents on one repo without conflicts Run several Claude Code agents on one repository safely: worktrees, subagents, agent teams, cross-session messaging, and a clean landing routine, step by step. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 7 min read To run multiple Claude Code agents on one repo without conflicts, give each agent its own checkout (`claude --worktree ` creates a git worktree per session), split the work so no two agents own the same files, let the sessions tell each other what changed, and land each branch with a rebase plus a test run. Worktrees stop agents from overwriting each other's files while they work; they do not stop the work from clashing when it merges, so the last two steps matter as much as the first. ## Pick the right way to run agents in parallel As of October 2026, Claude Code's docs list several ways to work on more than one task at once. They differ in who coordinates the work and whether the workers can edit the same files. | Approach | What it is | File isolation | |---|---|---| | Parallel sessions you start yourself | One `claude` per terminal, usually one worktree each | Yes, with `--worktree` | | Subagents | Workers inside one session that do a side task and return a summary | Optional, with `isolation: worktree` | | Agent view (`claude agents`) | One screen to dispatch and watch background sessions (research preview) | Dispatched sessions move into their own worktree before editing | | Agent teams | A lead session plus teammates with a shared task list and messaging (experimental, off by default) | No; the docs say to partition files | If you want to drive each agent yourself, use parallel sessions in worktrees. If one conversation should fan work out and collect results, use subagents. The rest of this guide assumes parallel sessions, since that is where most collisions happen. ## Step 1: give each session its own worktree Claude Code creates and manages worktrees for you: ```bash claude --worktree feature-auth ``` In a second terminal: ```bash claude --worktree fix-billing ``` Each command creates a worktree under `.claude/worktrees//` on a new branch named `worktree-`. If you omit the name, Claude generates one. Claude Code's docs put the benefit plainly: "Running each Claude Code session in its own worktree means edits in one session never touch files in another." While a session is isolated, Claude Code also blocks edits and git commands that target the main checkout. Two pieces of housekeeping: - Add `.claude/worktrees/` to `.gitignore` so worktree contents do not show up as untracked files. - A worktree is a fresh checkout. Untracked files such as `.env` are missing, and dependencies are not installed. List the gitignored files you need in a `.worktreeinclude` file at the project root (same syntax as `.gitignore`), and ask Claude to install dependencies in each new worktree. ```text .env .env.local config/secrets.json ``` When you exit, Claude removes a clean, unnamed worktree automatically and asks before removing one that still holds work. If you prefer plain git, `git worktree add ../project-feature-a -b feature-a` followed by `cd ../project-feature-a && claude` does the same job. ## Step 2: split the work by files, not just by task Worktrees isolate edits during the session, but two agents that both change `src/auth/session.ts` will still produce a conflict when their branches meet. Before you start agents, decide which files or modules each one owns. Claude Code's agent teams docs give the same advice for teammates, who share one checkout: "Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files." Good splits follow module boundaries: one agent on the API layer, one on the UI, one on tests for code that is already merged. Bad splits are "agent A does the refactor, agent B adds the feature" in the same files. ## Step 3: let the sessions talk to each other Agents in separate worktrees cannot see each other's changes. Claude Code's cross-session messaging (v2.1.224 or later on macOS and Linux, on by default when the session meets the requirements) lets Claude list your other sessions on the machine and send them plain-text messages. The docs describe the exact case: "When a change in one session breaks what another is building on, Claude can warn that session before you notice." You can prompt it directly: ```text Let @fix-billing know I renamed getInvoice to fetchInvoice in src/billing/api.ts ``` Two limits to keep in mind. Claude decides when to send a message, so a warning depends on the sending agent noticing that its change matters to someone else. And messages are plain text: the receiving agent still has to go and read the code. Run `/list-agents` to see which sessions Claude can reach. ## Step 4: land each branch with a rebase and a test run When an agent finishes, land its branch against the latest main, not the main it started from: ```bash git fetch origin git rebase origin/main # run your test suite here git push ``` Rebasing first surfaces textual conflicts in one branch at a time. Running tests after the rebase catches the conflicts git cannot see, such as one agent renaming a function that another agent's new code still calls. Land branches one at a time, and have each later agent rebase onto what already landed. ## Step 5: keep an eye on cost Every parallel session sends its own requests. Claude Code's docs note that running several sessions or subagents at once multiplies token usage, and that agent teams "use significantly more tokens than a single session." Three focused agents with clean file boundaries usually beat six that keep stepping on each other. ## How Cork helps The steps above isolate files and rely on agents choosing to tell each other things. Cork makes that coordination automatic. 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. For this problem specifically: - **Briefing:** when a Claude Code agent starts or gets a prompt, it is handed the exact signatures, callers and recent changes of the code it is about to touch, so it searches less. - **Live awareness:** when another agent renames a function or changes a signature yours depends on, your agent hears it on its next step, without the other agent having to decide to send a message. - **[Write gate](https://corkcli.com/blog/write-gate):** an edit against code another agent is changing right now is held until your agent has their version. That makes a single shared checkout workable when bootstrapping a worktree per agent is too slow. - **Landing:** `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes, which is Step 4 done for you. Hooks in Claude Code run this with no extra model calls. Cork Free covers unlimited agents and repos on one machine with no account; the paid plan extends it to teammates' machines. Install it once for every repo on the machine: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### Can two Claude Code sessions work in the same folder? Yes, but nothing in plain Claude Code stops them from editing the same file, and the last write wins. Use `claude --worktree` for separate checkouts, or a coordination layer that holds conflicting edits. ### How many Claude Code agents can I run at once? Claude Code's docs do not set a fixed number for sessions you start yourself; the practical limits are your usage limits and your ability to review the output. For agent teams, Claude Code's docs suggest starting with 3 to 5 teammates. ### Do worktrees prevent merge conflicts between agents? No. They prevent agents from overwriting each other's uncommitted files. Conflicts, including a renamed function that another branch still calls, appear when the branches merge. ### Should I use subagents or separate sessions? Use subagents when one conversation should delegate a self-contained task and get a summary back. Use separate sessions when you want to steer each piece of work yourself. ## Sources - - - - - - ## Related reading - [Cork vs Claude Code agent teams: one session's crew, or every agent on the repo](https://corkcli.com/blog/cork-vs-claude-code-agent-teams): Cork vs Claude Code subagents, agent teams and cross-session messaging: what each coordinates, where agents collide, and when to use both together. - [Claude Code agent teams vs separate sessions on one repo](https://corkcli.com/blog/claude-code-agent-teams-vs-separate-sessions): Claude Code agent teams vs separate sessions on one repo: how each works, token cost, same-file conflicts, worktrees, and when to pick which (October 2026). - [Setting up Claude Code multi-agent work on Windows (Git Bash and PowerShell)](https://corkcli.com/blog/claude-code-multi-agent-windows-setup): Run several Claude Code agents on Windows: install, Git Bash vs PowerShell, worktrees, hooks in either shell, agent teams, messaging and WSL, per the docs. - [Agent-to-agent messaging between coding agents: how it works](https://corkcli.com/blog/agent-to-agent-messaging-coding-agents): How coding agents message each other as of October 2026: Claude Code SendMessage, team mailboxes, cross-session sockets, A2A, and what a useful message holds. [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/run-multiple-claude-code-agents-one-repo