Two Coding Agents, One Repository, No Collisions

Two coding agents can work on one repository productively when each has a separate working directory, a clear assignment, and a controlled path into the shared branch. Different branches alone are insufficient if both agents edit the same checkout. This walkthrough uses Git worktrees to separate file edits and a coordinator to handle integration.

1. Establish a committed starting point

Start in a clean checkout. Run git status --short, then commit intended changes or set unrelated work aside. Both agents should begin from the same committed state so differences remain attributable to their assignments.

Create the integration branch with git switch -c integration/two-agents. Record its starting commit using git rev-parse HEAD. Keep this checkout for the coordinator, who will review and combine completed work. The coordinator can be a person or a separate, explicitly assigned agent session.

2. Create one worktree per agent

From the coordinator checkout, run git worktree add -b agents/api ../repo-api integration/two-agents, followed by git worktree add -b agents/ui ../repo-ui integration/two-agents. These commands assume the branch names and destination directories do not already exist.

Each worktree has its own checked-out files and index. Git objects and repository references remain shared, so worktrees isolate edits without creating completely independent repositories. Launch each agent inside its assigned directory and have it confirm its location and branch before editing. Avoid repository-wide maintenance while both sessions are active.

3. Divide ownership around a stable interface

Assign concrete paths and acceptance criteria. For example, the API agent owns src/api/ and its tests; the UI agent owns src/components/ and its tests. Directory boundaries help, but the interface between their changes matters just as much.

Agree on request fields, response shapes, error behavior, and representative fixtures before implementation. Commit that agreement before creating the worktrees, or distribute the same specification to both agents. Give shared files such as dependency manifests, lockfiles, generated clients, and configuration a single owner.

• The API agent implements the agreed response and validates failure cases.
• The UI agent develops against an agreed fixture with the same response shape.
• The coordinator handles requested changes to shared files and communicates interface revisions.

4. Isolate runtime resources too

Separate directories do not prevent both agents from starting servers on the same port or modifying the same development database. Assign distinct ports, database names, temporary directories, and output locations where the project requires them.

Install dependencies in each worktree according to the repository’s normal setup. Check whether environment files are ignored and therefore absent from a new worktree. Supply local configuration deliberately. If both agents run migrations, give them separate databases or containers so one session cannot invalidate the other’s tests.

5. Give each session a narrow operating brief

Tell each agent its working directory, branch, owned paths, interface contract, required checks, and completion format. Require it to request coordination before touching shared files. Ask for a commit plus a concise handoff covering changed behavior, tests run, and remaining limitations.

CodeRelay Hub can provide model access through one endpoint for tools such as Claude Code, Codex, and Gemini CLI. Keep repository isolation and ownership rules consistent across those sessions; model routing does not coordinate filesystem access, shared services, or Git integration.

6. Integrate completed commits sequentially

Have each agent finish its changes and leave a clean worktree. In the coordinator checkout, review the first branch and run git merge --no-ff agents/api. Run the relevant checks before merging agents/ui.

Resolve conflicts in the coordinator checkout. When resolving a conflict requires a behavior decision, compare both implementations against the agreed interface. A successful textual merge does not prove compatibility: field names, validation rules, and assumptions can diverge across different files.

7. Validate the combined result and clean up

Run the project’s build, static checks, and relevant tests on the integrated branch. Exercise the interaction between the two changes, including one failure path. Inspect the final diff for unrelated edits and unexpected changes to shared files.

After integration is accepted and both worktrees are clean, remove them with git worktree remove ../repo-api and git worktree remove ../repo-ui. Retain the integration branch for normal review and delivery.

Open a free workspace to try your next paired workflow.