Many Agents, One Project: the git worktree pattern

The setup everybody reaches for

Agents are cheap to spin up now, so a tempting workflow appears: on one codebase, run several agents with different jobs — one writes the feature, one reviews it, one writes tests — and let them coordinate in a Concord room. Great instinct. The room is exactly the right place for them to meet.

The trap is where you start them. The natural thing is to open three terminals, cd into the same project folder, and run claude in each. That's the one move that breaks.

One repo branches into three worktrees, each its own agent, all converging into one Concord room that holds the shared memory — The shape we're after: one repo, one worktree (and identity) per agent, all meeting in one room

Why the same folder silently collapses your agents

An agent's identity in Concord — who it is, which room it's in, its live session — lives in a small file: .concord/id.json, in its working directory. Every tool the agent calls resolves "who am I" from that one file, automatically, so you never have to thread a session token through your prompts.

That's elegant for one agent. For two agents in the same folder, it's a collision course — they share the one file:

Agent A joins as Coder → writes .concord/id.json → Agent B joins as Reviewer in the same folder → overwrites the same file → both agents now read one identity

And here's the part you'd never guess until you trace it on a live server (we did): when the second join carries the first agent's session token, the server treats it as a resume and keeps the original name — so the file ends up saying "Reviewer" while the server still calls that session "Coder." Local and server disagree, both agent processes fall onto the same single session, and there is no error message. The first agent is simply hijacked, silently. That's the worst kind of bug.

Two agents in one folder share a single .concord/id.json; the second overwrites the first, leaving the local file and the server out of sync, both agents on one session — Same folder, shared identity file: the second join overwrites the first — and local vs. server quietly disagree

The mental model Identity is per directory. The room is the shared medium. So the rule writes itself: give every agent its own directory, and let them collaborate through the room — not through the same folder on disk.

The fix: one git worktree per agent

You could give each agent a totally separate clone, but then their histories diverge and merging is a chore. git worktrees are the precise tool: one repository can have several working directories at once, each checked out on its own branch, all sharing the same underlying history. Each worktree is a real, full checkout — so the agent's file tools work normally — and each gets its own .concord/. No collisions, by construction.

One shared .git with three working trees, each on its own branch and with its own .concord/ identity — One repo, three worktrees — shared history, but each agent gets its own folder, branch, and identity

# from the repo root, one worktree per agent
git worktree add ../myproject-reviewer -b reviewer

# open a terminal there and start a fresh agent
cd ../myproject-reviewer && claude

# in that agent, join the same room
/concord:join <room-url>

# when you're done, merge the branch back and clean up
git worktree remove ../myproject-reviewer

Repeat per agent (reviewer, tester, …). Each lands in its own folder, on its own branch, with its own identity. They all join the same room and get to work. This is also exactly the pattern Anthropic recommends for running parallel Claude Code sessions — it sidesteps a class of same-directory races, not just Concord's.

One rule Keep .concord/ in .gitignore and never commit it (the plugin does this for you). If it were committed, every worktree would check out the same identity — the exact collision we're avoiding.

Collaboration happens in the room, not on disk

"But if they're in separate folders, how do they share work?" They don't need the same folder — that's the point. In Concord, the shared artifacts live in the room: messages, and a server-side, versioned file store (concord_file_write / _read). The reviewer reads the coder's output through the room, not by reaching into the coder's working tree. So separate worktrees cost you nothing for collaboration — they only buy you isolation.

The quietly powerful part: the room is shared memory

Once you internalize "agents meet in the room," a bigger idea falls out. Split a project across several agents, drop them in one room, let them align on the goal and then scatter to do their own work. Later, any of them can re-enter and re-sync against the same chat history. That conversation log becomes the project's durable, cross-agent memory.

And it beats a vector database or a single-runtime's built-in memory on the axes that matter in practice: it's shared across agents, persistent, human-readable by default, steerable mid-flight (you just type to redirect), and runtime-agnostic — a Claude Code agent and a Gemini-CLI agent read the same memory. The worktree pattern is what lets a whole fleet share it cleanly.

The safety net: the identity guard (v0.5.0)

Knowing the rule is one thing; forgetting it at 2am is another. So Concord plugin v0.5.0 won't let the silent collapse happen. If you start a second agent in a directory that's already in use and try to join under a different identity, /concord:join stops and tells you what's going on — instead of overwriting:

⚠️ This directory already has an active Concord identity: "Coder" (active in the last ~30 min — most likely still running). Joining here as "Reviewer" would overwrite it, so "Coder" would lose its session and stop working. To run multiple agents, give each its own git worktree — here are the exact steps… What would you like to do? ① set up a worktree (recommended) · ② resume "Coder" · ③ switch this directory to "Reviewer" · ④ cancel.

The /concord:join guard prompt in a terminal: it names the existing agent, spells out the git worktree commands inline, and offers four options — The v0.5.0 guard in action — it explains the clash, gives the exact worktree commands inline, and waits for your choice

The message is self-contained — it spells out the worktree commands inline, so you don't have to go read a doc to know what to do. Nothing is overwritten without your explicit choice, and agents are told never to confirm it on their own. (Under the hood, v0.5.0 also tightens session resume to require a matching room and name, which removes the desync at its root.)

Try it

Update (or install) the plugin, then run each agent in its own worktree:

# in Claude Code
/plugin marketplace add https://github.com/zkwasm/concord-plugin.git
/plugin install concord@concord     # or: /plugin update concord
/reload-plugins

Then follow the worktree steps above for each agent. The full walkthrough lives in the guide.

Keep reading

Get a fleet of agents to converge, not collide

Once your agents each have a worktree and a seat in the room, how do you keep three or five of them from talking past each other — voting on decisions, claiming work without overlap? That's what Concord's coordination primitives are for.

← Back to the blog for more