Guided journey

Run Two Coding Agents Without Losing Work

An intermediate journey: partition work between two coding agents with git worktrees, assign file ownership, merge one branch at a time, and test the combined result.

Intermediate1 day9 milestones13 min read
You walk away with

Two agents working on one repository in parallel, each in its own worktree, with an explicit merge order and a test run on the combined result rather than on each branch.

Assume you have

A project with two pieces of work that are genuinely independent, and comfort with branches and merges.

Stack used

Git worktrees and branches. Any two agents, or the same agent twice.

The project

Take two independent pieces of work in one repository and run them through two coding agents at the same time, without either overwriting the other. You will partition the work, give each agent its own filesystem, define what they are allowed to touch, and merge the results deliberately.

By the end you will have: two branches from the same base, one worktree per agent, a written file-ownership map, a merge performed one branch at a time, and a passing test run on the combined result.

Before you start

  • Two tasks that could ship independently, and a repository where neither is half-finished.
  • Git available, with a clean working tree.
  • How to Stop Two AI Agents Editing the Same File as the reference. This journey is the working session built on it.

Milestone — Decide whether the work can be parallelised

Build: a written answer to “do these two tasks touch the same files?”

Running two agents on work that overlaps does not make it faster. It makes it a merge conflict with extra steps, and it loses work in the process if you have not isolated them yet.

Do it

  1. List the files each task will need to change, from the task description, not from hope.
  2. Mark the overlap. Router files, schema definitions, shared configuration, and base components are the usual collisions.
  3. If the overlap is large, split the work differently, or run the second task after the first.

Done when the two file lists are disjoint, or you have decided to sequence them. What Is Multi-Agent Coding (and Why Do Agents Conflict With Each Other)? explains the overlap patterns.

Milestone — Freeze the interface first

Build: a stub the two tasks share, committed before either agent starts.

Two tasks that must call each other need a boundary that neither needs to change. Defining it first is what turns overlapping work into independent work.

Do it

  1. Write the function signature, type, or route that both sides depend on, with a stub implementation.
  2. Commit it to the base branch.
  3. Give both agents a task description that says the interface is fixed and must not be edited.

Done when both agents can work against the interface without modifying it. How to Write a Spec an AI Coding Agent Can Actually Follow is how to phrase the constraint so it is respected.

Milestone — One worktree and branch per agent

Build: two working directories from the same base commit.

This is the change that makes the whole journey safe. Without it, the second agent to write wins and neither reports a problem.

Do it

  1. Create a worktree and branch for each task, from the current base commit.
  2. Confirm each agent’s working directory is the worktree, not the main checkout.
  3. Note the base commit hash, so you know what both branched from.

Done when each agent has its own directory and neither can see the other’s uncommitted changes.

git worktree add ../agent-a -b agent/a-<task>
git worktree add ../agent-b -b agent/b-<task>
git log --oneline -1   # record this base commit for both branches

Milestone — Assign file ownership, in writing

Build: a map of which paths belong to which agent, and which belong to neither.

Worktrees stop destructive overwrites; ownership stops merge conflicts. The shared files are the ones to name explicitly, because those are where the agents will collide.

Do it

  1. Give each agent an exclusive set of directories or modules.
  2. Mark the shared files — router, schema, configuration, dependency manifest — as yours to edit after the merge, not theirs to touch.
  3. Put the constraint in each agent’s task description, and in the project rules file if you have one.

Done when every file either has one owner or is marked as yours. What Is AGENTS.md (and Why Does Your Agent Ignore Your Rules)? is where the ownership rule belongs for future sessions.

Milestone — Start both agents with their boundary stated

Build: two running agents, each told what it owns and what is off limits.

An agent that is not told the boundary will interpret the task generously, which is exactly how it ends up in a shared file.

Do it

  1. Give each agent its worktree path and its file ownership explicitly.
  2. State that the shared interface and the other agent’s directories are out of scope.
  3. Keep each session’s context scoped to its own task — How to Manage an AI Agent’s Context Window.
  4. If either agent needs a shell, run it inside its own container rather than on your machine — Journey: Give Your Coding Agent Its Own Sandbox.

Prompt your agent

You are working in the worktree at ../agent-a on branch agent/a-<task>.

Ownership:
- You may create and edit files under src/billing/ and tests/billing/.
- Do not edit src/routes/index.ts, db/schema.ts, or package.json.
  Flag anything that seems to require a change there.

The interface in src/billing/types.ts is frozen. Do not change it.

When you are done, summarise the files you changed and why.

Done when both agents are working in their own directories and neither has touched a shared file.

Milestone — Review each branch on its own

Build: two reviewed branches, each passing its own tests.

Review them separately before the merge. This is the point where you can still reject a change cheaply.

Do it

  1. Run the full test suite inside each worktree.
  2. Review each diff for the usual generated-code failure patterns.
  3. Check neither branch modified a shared file — if one did, resolve that now, on its branch.

Done when both branches are approved independently and each suite passes. How to Review AI-Generated Code Like a Senior Engineer is the review checklist.

Milestone — Merge one at a time, by intent

Build: both branches merged, with conflicts resolved deliberately.

The first merge is usually clean; the second is where the shared files collide. Resolve those by reading both intents, not by picking a side.

Do it

  1. Merge the first branch and run the tests again on the result.
  2. Merge the second and inspect conflicts in the shared files; resolve them as a design decision.
  3. If a shared file needed both changes, make that edit yourself after the second merge.

Done when both changes are present and the shared files contain a coherent combination. How to Resolve a Git Merge Conflict and What Is a Merge Conflict? cover the mechanics.

Milestone — Test the combination, not the parts

Build: a passing full suite on the merged result.

This is the milestone people skip, and it is the one that finds the real bugs. Each branch passed alone; only the combination can fail.

Do it

  1. Run the complete test suite on the merged branch.
  2. Look specifically for duplicate registration, conflicting migrations, and repeated column additions.
  3. Run it once more after any conflict resolution, because resolution is a code change.
  4. Exercise the two features together in a running app, not only in tests.

Done when the suite passes on the merge and you have used both features at once. How to Test AI-Generated Code covers the integration gaps unit tests miss.

Milestone — Clean up, and record what you learned

Build: removed worktrees and branches, and a note about the collision points.

The next parallel session is easier if the ownership map from this one survives it. The collisions you hit are the ones you will hit again.

Do it

  1. Remove the worktrees and delete the merged branches.
  2. Update the file-ownership map, including any shared file that turned out to be a collision point.
  3. If the same shared file collided twice, split it or move the shared edit into the base branch’s interface.

Done when the worktrees are gone and the ownership map is better than the one you started with.

Ship checklist

  • The two tasks touch disjoint files, or were sequenced instead.
  • A shared interface was committed before either agent started.
  • Each agent has its own worktree and branch from the same base.
  • File ownership is written down, including the shared files.
  • Both agents were told the boundary explicitly.
  • Each branch was reviewed and tested separately.
  • Branches were merged one at a time, with conflicts read not assumed.
  • The full suite passes on the merged result.
  • Both features were exercised together.
  • Worktrees removed and the ownership map updated.

Where this journey goes wrong

  • Two terminals, one checkout. The last writer wins and neither agent reports it.
  • Assigning tasks by description rather than by path. The descriptions differ; the files do not.
  • Both agents editing the router or the schema. Guaranteed conflict in the file that is hardest to merge.
  • Merging both branches at once. You lose the ability to see which change caused a conflict.
  • Resolving a conflict by taking one side. Both changes are usually individually correct.
  • Testing each branch and calling it done. The integration failures are invisible that way.
  • Leaving the worktrees behind. They accumulate, and the next session starts from the wrong directory.

FAQ

When is parallelising not worth it?

When the two tasks both need to change the same files. If both features touch the same schema, the same router, and the same configuration, they are one unit of work and should run in sequence. Parallel agents pay off when the interface between the work is stable and neither task needs to modify it.

Why test the merged result rather than each branch?

Because the interesting failures only exist in the combination: two migrations that assume a different order, two handlers registered for the same event, two columns added with the same name. Each branch passes its own tests by construction. The merged result is the only thing that ships, so it is the only thing worth testing.

Does this work with the same agent run twice?

Yes. Two instances of the same tool in two worktrees behave exactly like two different tools, and the constraints are the same: separate directories, one owner per file, merge sequentially. The only extra care is that identical agents tend to make identical choices, so the interface between their work needs to be explicit rather than assumed.

Share: