Running several coding agents on one repo without collisions

One agent is fast. Two or three in parallel can be much faster, or they can spend the afternoon overwriting each other's files, redoing the same story and leaving you to untangle a merge. The difference is almost entirely setup: separate working copies, work split along clean lines, and one shared place that says who is doing what.

This guide is a practical setup for running several coding agents (several Claude Code sessions, or a mix of Claude Code, Cursor and Codex) on one repository.

What goes wrong

Before the setup, the failure modes it prevents:

• Same files, same time. Two agents edit src/lib/auth.ts in one working directory. One of them wins; the other's changes vanish or get mangled.
• Same task twice. Both agents were told "continue" and both picked the obvious next task.
• Wrong order. One agent builds the settings page before the other has built the API it calls, then mocks the API and moves on.
• Invisible progress. Each agent's state is in its own transcript. You can't tell who finished what without reading all of them.
• Merge debt. Long-lived branches drift, and the final merge undoes a day of parallel work.

Rule 1: one working copy per agent

Agents running in the same directory share one set of files, one dev server and one git index. Give each agent its own working copy. The lightest way is git worktrees: extra checkouts of the same repository, each on its own branch, sharing one .git store.

# from your main checkout
git worktree add ../app-billing -b feat/billing
git worktree add ../app-onboarding -b feat/onboarding

# start one agent in each
cd ../app-billing && claude
cd ../app-onboarding && codex

Each worktree has its own files and branch, so agents can't step on each other's edits. When a branch is merged, remove its worktree with git worktree remove ../app-billing.

A few practical notes:

• Ports. Two dev servers can't both listen on 3000. Give each worktree its own port (PORT=3001 pnpm dev), and say so in the agent's first message.
• Local databases. If tests write to a local database file, each worktree needs its own, or tests will interfere.
• Dependencies. Each worktree needs its own node_modules (or equivalent). Install once per worktree.
• Secrets. Copy local env files into each worktree yourself; don't ask agents to create them.

Rule 2: split work along features, not files

Parallel work only goes smoothly when the pieces don't overlap. The best seam is the feature: billing in one branch, onboarding in another. Splitting a single feature across agents ("you do the API, you do the UI") sounds efficient and usually produces two halves that don't fit.

Good parallel splits:

• Two unrelated features (billing and onboarding)
• A feature and its tests or docs, after the feature's interfaces are settled
• Independent bug fixes in different parts of the code

Risky splits:

• Two halves of one feature at the same time
• Anything that changes a shared schema, config or design system file
• Refactors running next to feature work

When stories record the files they're likely to touch, you can see overlap before it happens. In Klio, each story has "likely files", and when two stories in a feature share files the board suggests an order.

Rule 3: one shared board with claims

Agents in separate worktrees can't see each other. They need one shared place that says what exists, who has what, and what's done. That place should enforce claims: when an agent starts a story, no other agent can take it.

With an MCP board, the flow per agent is:

1. get_next_work returns the next story and reserves it briefly for this agent, so two agents asking at the same moment get different stories.
2. start_issue claims it. If another agent already holds it, the call is refused and the agent picks something else.
3. complete_issue releases it to review. release_issue gives it back if the agent stops.

Each agent sees what the others changed since it last looked, because get_next_work and get_project_context lead with a short digest of other agents' activity.

Rule 4: make order explicit

If story B needs story A, write it down. Klio stories take a dependsOn list; a story waiting on unfinished work isn't offered by get_next_work and can't be started, so "continue" never picks something that can't be built yet. In other tools, a "blocked by" link plus a line in your rules file ("don't start blocked issues") gets you most of the way.

Rule 5: hand whole features to specific agents

Instead of letting every agent pull from one queue, assign features. "Claude Code takes billing, Codex takes onboarding." Each agent then only gets stories from its own feature, and you always know which branch holds which work.

In Klio, assignment is a field on the story or the whole feature. You can set it from the board, or have an agent do it:

Assign feature KLIO-F12 to Codex and KLIO-F13 to Claude Code,
then start on KLIO-F13.

The agent calls update_issue with the feature ID and an assignee, which hands every story in that feature over at once.

A worked example

You have two features planned: Billing (four stories) and Onboarding checklist (three stories). Neither touches the other's files.

1. Create two worktrees, feat/billing and feat/onboarding, and install dependencies in each.
2. Assign Billing to Claude Code and Onboarding to Codex on the board.
3. In the billing worktree: "continue". Claude Code gets Billing story 1, claims it, builds it, ticks its criteria and completes it. It asks you for a Stripe or Polar key with flag_for_human when it needs one.
4. In the onboarding worktree: "continue". Codex gets Onboarding story 1, and so on.
5. As stories land in review, you check them on the board and merge each branch when its feature is done. Short features mean short-lived branches and small merges.
6. If you add a third agent, give it a third feature and a third worktree.

Shared files: migrations, config and design tokens

Some files are touched by almost every feature: database migrations, route config, environment variable lists, shared UI tokens. They're where parallel agents collide even when the features are separate.

• Migrations. Two branches each adding "migration 0021" will conflict on merge. Either reserve numbers per feature up front, or make the agent check the latest number on the main branch right before it writes one, and renumber on merge if needed.
• Config and env lists. Ask agents to add new entries at the end of the file rather than in alphabetical order; conflicts at the end are trivial to resolve.
• Design tokens and shared components. Treat changes to these as their own small story, done by one agent and merged first, before features build on them.
• Lockfiles. Two agents adding different dependencies produce lockfile conflicts. Regenerate the lockfile on merge instead of hand-merging it.

Signs your setup isn't working

• You keep resolving the same merge conflicts in the same files: split the work differently, or land the shared change first.
• Agents mock things another agent is building: you're missing a dependency between stories.
• You can't say which agent is on what without asking them: you need claims, or a board that shows them.
• Review is the bottleneck: run fewer agents, or make stories smaller so each review is quick.
• One agent finishes and sits idle while another is stuck: assign work by feature so each has its own queue.

Reviewing parallel work

More agents means more output to review. Keep it manageable:

• Review by story, not by transcript. Each completed story should come with a short summary of what changed and which criteria passed.
• Keep "done" human. Agents move work to review; you move it to done. It's the cheapest quality gate there is.
• Merge often. A feature branch that lives a day is easy to merge; one that lives two weeks isn't.
• Run the tests on the merged result, not just each branch.

When not to parallelise

Parallel agents are worth it when the work splits cleanly. They're not worth it for a single tightly-coupled feature, for early prototyping where the shape is still changing, or when you can't keep up with reviewing. One focused agent with good stories beats three agents and a messy merge.