multiple claude code instances on one repo.

published 2026-10-17

you can run multiple Claude Code instances on one repository at once: Claude Code’s docs name no limit on terminal sessions. give each a worktree with claude --worktree <name>. before your agent edits a file a teammate’s Claude Code, Codex or Cursor agent changed in the last 30 minutes or on an unmerged branch, agentmash tells it who and when.

how many claude code instances can you run?

no fixed number for the terminal sessions you start yourself. Claude Code’s docs, checked on 2026-10-16, name no limit on how many of those run at once. some of the features that run sessions or agents for you have caps of their own, listed below. the docs do state the cost. the page comparing the parallel approaches notes that running several sessions or subagents at once multiplies token usage, and agent view’s docs estimate that ten background agents use quota about ten times as fast as one. each session sends its own requests, counted against the plan or API account it’s signed in to.

the other numbers the docs state:

• subagents. by default, when 20 subagents are running in a session, spawning another fails until one finishes. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes that number. the limit needs Claude Code v2.1.217 or later and isn’t enforced in a session with ultracode on (subagents).
• agent teams. there is no hard limit on teammates, and the docs suggest starting with three to five (agent teams).
• /batch. it splits one large change into 5 to 30 independent units, shows you the plan, and once you approve it runs each in a background subagent in its own worktree. it needs a git repository or a WorktreeCreate hook (commands).
• dynamic workflows. a workflow runs up to 16 agents at once by default, fewer on a machine with fewer CPUs. CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS sets it anywhere from 1 to 256, in Claude Code v2.1.269 or later (workflows).
• Remote Control. in server mode (claude remote-control), one process runs at most 32 concurrent sessions by default, and --capacity changes that. outside server mode, each Claude Code instance supports one remote session at a time (Remote Control).
• projects. a project at claude.ai/code or in the desktop app runs its threads in parallel with no fixed number, and starts at most 200 new threads a day across your projects. projects are in public beta on Pro and Max plans, rolling out gradually, and aren’t on Team or Enterprise plans yet (projects).

on a Pro, Max, Team or Enterprise plan, /usage breaks recent usage down by skills, subagents, plugins and MCP servers (costs). the breakdown is computed from session history on that machine, so a second laptop’s sessions aren’t in it.

what goes wrong with two sessions in one checkout

opening a second terminal and running claude in the same folder works, and for reading (a review, a question about the code) it’s fine. both sessions share one working tree, one index and one checked-out branch, so once both write, each can edit files the other is changing.

• the branch moves under a session. in anthropics/claude-code#60295 (May 2026), two sessions in one working directory were on two branches. when one ran git checkout, the other’s files changed under it, and it carried on as if it were still on its own branch. the reporter’s fix was a git worktree per branch.
• uncommitted edits collide. in #52051 (April 2026), another user reports uncommitted edits from two sessions colliding in one tree, and a branch switch in one breaking the other.
• a whole-file write. Claude Code’s Edit matches its old_string against the file as it is now, so an edit over lines the other session changed doesn’t apply, and Claude reads the file again (tools reference). Write replaces the whole file with the content it’s given and doesn’t merge, and newer models can overwrite a file they haven’t read in the session when reading it wouldn’t need a permission prompt and the Read tool is available, so a whole-file write can replace the other session’s change.

how to run multiple claude code sessions in parallel

give each session its own worktree. a git worktree is a second working directory of the same repository, with its own files and its own branch, sharing one history. Claude Code makes one for you:

-w is the short form. per Claude Code’s worktree docs, the worktree goes under .claude/worktrees/feature-auth/ at the repository root, on a new branch named worktree-feature-auth. run the command again with another name in a second terminal for a second isolated session, or leave the name out and Claude picks one. in an interactive session, in a folder where you haven’t run Claude Code before, --worktree exits with an error until you run claude there once and accept its trust prompt (worktrees), and in a repository with no commits yet the command fails (common workflows).

three details from the worktree page that matter when several sessions run at once:

• where it branches from. by default a new worktree starts from the repository’s default branch on the remote, usually main, so your unpushed commits aren’t in it. set worktree.baseRef to "head" in your settings to branch from your local HEAD instead.
• what the isolation covers. while a session is in a worktree, Claude Code refuses its edits, commands and git redirects aimed at the main checkout. the docs say these checks don’t track which files a shell command writes, so a cp or a shell redirect into the main checkout isn’t refused.
• what to ignore. add .claude/worktrees/ to .gitignore, so the worktrees’ files don’t show up as untracked in the main checkout.

a new worktree is a fresh checkout, without .env or installed dependencies unless you bring them in: what a worktree leaves out covers .worktreeinclude and the rest, and what happens to it when the session exits.

keep your linters and pre-commit hooks out of .claude/worktrees/ too. in #40850 (March 2026, Claude Code 2.1.87), a session in the main checkout hit a pre-commit hook that tripped over a config file inside .claude/worktrees/, called that worktree stale and deleted it while another session was working in it. the worktree docs say Claude Code locks a running subagent’s or background session’s worktree with git worktree lock; a lock stops git worktree remove, not an rm -rf like the one in that issue.

the desktop app has a worktree option next to the branch name when you start a session. in a git repository, a session you dispatch from agent view (claude agents, a research preview) moves into a worktree of its own before it edits files, unless worktree.bgIsolation is set to "none".

subagents vs separate claude code sessions

subagents are workers inside one session: Claude hands one a side task, it works in its own context window, and only its summary comes back, its requests counted toward the same usage limits as the main conversation. use them to keep one session’s context small, and separate sessions, each in its own worktree, for pieces of work you steer yourself.

agent teams and cross-session messaging

agent teams, experimental and off by default, let one lead session spawn teammates, separate Claude Code instances that share a task list and message each other; teammates don’t get worktrees, so the agent teams page asks you to give each one its own files. cross-session messaging, in Claude Code v2.1.224 or later (v2.1.234 on native Windows), lets Claude list and message your other Claude Code sessions, on this machine or, through Remote Control, on your other machines (cross-session messaging). both stay with one person’s sessions: can claude code sessions talk to each other? covers whose sessions a message reaches and what it carries.

claude code on multiple machines, across a team

in every approach on Claude Code’s parallel-work page, the workers are Claude sessions, and the two features above that coordinate them stay with one person: cross-session messaging reaches the sessions you run yourself, and an agent team lives inside one lead session.

on a team, alice runs two Claude Code sessions in worktrees on her laptop, bob works in Codex, carol in Cursor, all on the same repository. each worktree is a clean checkout on one machine, and none of them knows what a teammate’s session is changing until someone pushes and someone else pulls or merges. with everyone isolated properly, three things still go wrong:

• the same file on two branches. your session and alice’s both change src/models/user.ts, each in its own checkout. nobody is told, and any conflict shows up when someone merges.
• a break across files. alice’s session changes the signature of createUser in src/models/user.ts. your session, in src/api/handlers.ts, keeps calling the old one. the two files share no path, so git can merge both changes without a conflict, and the call is still wrong.
• a teammate in another tool. bob’s Codex and carol’s Cursor are outside every approach on that page: they aren’t Claude sessions, and they aren’t yours.

what agentmash adds for teammates

agentmash gives each repository one room. hooks in each developer’s coding agent report its edits there, and every worktree of the repository reports to that same room, each on its own branch. agentmash compares each developer’s edits with their teammates’, never with their own.

before an edit, your agent is told when a teammate’s agent changed the same file: within the last 30 minutes by default, or on a branch of theirs that isn’t merged yet, which the room remembers by person, branch and file for up to a week, until it merges. Cursor’s adapter hears less of that memory: only work from the last 48 hours by default, on a branch the Cursor user hasn’t worked on, in a file they haven’t changed since. in JavaScript and TypeScript it also warns about the break across files. when a teammate’s Claude Code agent changed an exported createUser within the same 30 minutes, your agent is told before it edits a file that imports it, whatever directory that file is in. the week-long branch memory is by file, not by name, and a change made in Codex or Cursor is matched by path only.

the advisory is worded mostly by where the teammate’s change is. on another branch, or in a clone of their own, it’s PARALLEL EDIT: there’s nothing to re-read, so the agent is asked to keep its edit additive, not to reformat or reorder, and to name any divergence in its reply. in the same checkout, a change from the last five minutes is ACTIVE COLLISION, or STALE READ once the teammate has gone, and the agent is asked to re-read the file before it edits; an older one is RECENT EDIT. when a hook can’t tell which checkout a change came from, it picks the same-checkout level and says what to do either way. a confirmed change to a name your file imports keeps its level after the teammate has gone: ACTIVE COLLISION in the same checkout, PARALLEL EDIT from another branch or clone. the five levels have the exact wording.

if both changes happen anyway, the person is told once, as the session finishes. this is the notice after your session changed src/models/user.ts on feat/login while alice’s changed it on main, word for word:

[AgentMash: OVERLAP] A file this session changed was also changed by alice@example.com,
so a person decides how the two changes come together: nothing was stopped, merged or
committed for either side.
• src/models/user.ts — also changed by alice@example.com.
  alice@example.com: last write 9 min ago on branch main — you are on feat/login
  while working on 'soft deletes' (+12/-3 lines, touching User, deletedAt).
  You both touched User — that is where the two changes are most likely to meet.
  Your side: 'add a login endpoint' (+8/-1 lines).
Look at both changes with alice@example.com before either one lands.

it only advises: the agent finishes as it would have. Claude Code, Codex and GitHub Copilot give this notice; Cursor’s adapter doesn’t.

set it up for a team

someone who can push to the GitHub repository connects it once, at agentmash.dev/install. nothing is committed to it and there is no pull request. then each developer runs this once per machine, with Node.js 18.12 or newer:

it signs in with GitHub and connects the coding agents it finds on the machine, each in its own user settings, never in a repository (Antigravity only when you ask for it by name). restart the agent, and its prompts and edits go to the room from the next prompt on. anyone who could push to the repository when they last signed in gets into its room, if that sign-in was within the last seven days. Codex adds a step, and Cursor gets the warning another way:

• Codex runs a hook only once you’ve reviewed and trusted it: open codex, type /hooks and approve agentmash (codex and claude code on one team).
• Cursor gets the warning as a refused first edit of a file a teammate is in, with the advisory as the reason, once per conversation and file every ten minutes, and the same edit again goes through (claude code and cursor on one team).

for a team where everyone runs Claude Code, claude code for teams goes through each hook. connect your coding agent has the steps for Claude Code and the other coding agents, and a prompt to paste into your agent that runs the login and tells you what’s left.

what reaches the room: who made each edit (your GitHub login, or the email in your git config, or your computer’s user name when there is neither), file paths, branch names, the shape of each change (its line counts and the names it touches) and the first 500 characters of a prompt, with an opaque id of the checkout each edit came from. your code stays on your machine unless the room turns diffs on or you share a session live. what leaves your machine has the full list.

which setup covers what

the worktree and agent-team rows are read from Claude Code’s docs, checked on 2026-10-16; the first row is from the issues and the tools reference above. the side by side with subagents and cross-session messaging is on claude code agent teams and agentmash, linked below.

what it doesn’t do

• it warns about teammates’ agents, never your own. two of your sessions, in two worktrees or in one checkout, both report as you, so neither is warned about the other, and a file both change raises no overlap notice. the same goes for a session on your second machine signed in as you. keeping your own sessions apart is the worktree’s job.
• an advisory informs the agent, and the edit goes ahead (in Cursor, on the agent’s second try). AGENTMASH_STRICT=1 blocks an edit into a teammate’s change until the agent acknowledges it with a reason, and acknowledging needs a POSIX shell. a teammate’s unmerged branch is never blocked on, strict mode included.
• it never merges, pushes or opens a pull request.
• symbols are read from the JavaScript and TypeScript family only. files in Python, Go and Rust are matched by path alone, so a break across files in them goes unseen.
• Codex patches and Cursor edits are reported without symbols, so a change made in either is matched by path only. a re-export barrel (export * from) breaks the chain between the file that defines a name and the file that imports it.
• after an advisory for a file, that file is quiet for ten minutes in that session about the teammates it named, so a further change one of them makes in that time isn’t said before the next edit of that file until the ten minutes are up; a teammate new to the file is still said (strict mode keeps no such pause). the notice about a teammate’s unmerged branch is said once a session.
• a shell command (sed, a heredoc) names no file, so nothing warns before it, in Claude Code, Codex or Cursor. in Claude Code and Codex, the files it changed are found in the checkout afterwards and reported.
• in a worktree session started from the desktop app, or one that moved into a worktree after it started (agent view’s background sessions do), Claude Code gives hooks the main checkout as the project, and that’s where agentmash looks after a shell command, so the files it changed in the worktree aren’t found. edits made with Claude Code’s own edit tools are still reported from the worktree they’re in.
• a check that runs past its budget, 1500 ms by default, lets the edit go ahead unwarned.