How to make two AI agents work together

When two AI coding agents work on the same repository, the easiest outcome is a merge conflict at pull request time. The hard part isn’t transport between agents; it’s knowing what the other agent intends to do next so you can avoid stepping on each other’s work.

What shared state looks like in practice

The goal is a single place both agents read and write so each sees the other’s intent and progress in real time. A branch, a file, or an MCP server can all serve this role, but they differ in effort and reliability.

Shared branch

Create a shared branch both agents target. Each agent checks out the branch, reads the latest files, edits, and pushes changes. The branch acts as the common ground, but merge conflicts still happen if both agents change the same lines.

Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way. Without a claim, the agents have no way to declare intent before they start editing, so conflicts surface only at push or PR review.

Shared file in the repo

Drop a single file like AGENTS.md at the repo root. Both agents read and append to it. You can include sections for each agent’s intent, progress, assumptions, and blockers. The file becomes the source of truth for coordination, but it doesn’t prevent the agents from editing the same code unless you enforce discipline in the prompts.

The file approach is lightweight but fragile. An agent can ignore the file, or a merge conflict can appear when two agents append to it at the same time. A better pattern is to use the file only for intent and rely on a branch or MCP server for the actual code changes.

Local MCP server

Run a local MCP server that exposes a shared state both agents call. The server maintains a work state: active claims, live overlaps, review-ready tasks, and open questions. Each agent calls the server before it starts editing to declare its intent and to see what the other agent is doing.

The MCP server is the most reliable option because it centralizes state and provides a single source of truth. It also surfaces overlap warnings before edits happen, so you prevent conflicts instead of cleaning them up later. The five tools you use to interact with the state are the same whether you run the server locally or deploy it to a team machine.

Declare intent before you start editing

The moment an agent begins editing, it must declare what it plans to do and where. Without this, the other agent has no way to know whether it should wait or proceed. Intent declaration is the difference between coordinated work and two agents stepping on each other’s toes.

Write intent into the shared file

Before an agent starts editing, it appends its intent to AGENTS.md under its section. The intent includes the files, modules, and the task it will perform. The other agent reads this section and can block itself if the intent overlaps with its own plans.

The shared file approach works for small teams and simple tasks, but it doesn’t scale. An agent can forget to write intent, or the file can become stale if an agent crashes mid-edit. A more dependable pattern is to use the MCP server’s claim_work tool, which enforces intent declaration and surfaces overlap warnings automatically.

Call the MCP server’s claim tool

An agent calls claim_work with the task, files, and modules it intends to edit. The server records the claim, checks for overlaps with other active claims, and returns a warning if there’s a conflict. The agent can then decide whether to proceed or wait.

The MCP server’s claim_work tool is the only mechanism that guarantees intent is declared and overlap is checked before edits begin. It also keeps a live record of all active claims, so you can query the state at any time with get_work_state.

Keep progress visible while you work

Intent declaration prevents conflicts at the start, but progress changes as the agent works. You need a place where both agents can read and write updates so the other agent can see assumptions, decisions, and blockers in real time.

Append updates to a shared file

Each agent appends its progress to AGENTS.md as it works. Updates include assumptions, decisions, questions, and blockers. The other agent reads these updates and can adjust its plan or raise a question if something doesn’t align.

The shared file pattern is simple but error-prone. An agent can forget to append an update, or the file can become stale if the agent crashes. A better approach is to use the MCP server’s update_task tool, which enforces structured updates and keeps the state live.

Call the MCP server’s update tool

An agent calls update_task with its typed intent, progress, assumptions, decisions, questions, blockers, and findings. The server records the update and makes it visible to the other agent immediately. The other agent can then call get_task_context to resume with the latest state.

The MCP server’s update_task tool ensures progress is visible and structured. It also keeps a history of updates, so you can revisit decisions or assumptions later. The tool is the same whether you use the local server or a team instance, so the workflow scales without changing the commands.

Hand off work cleanly before the PR

When an agent finishes its task, it must capture the changes, tests, risks, and decisions before marking the work review-ready. A clean handoff reduces the chance of surprises in code review and makes it easier for the next agent to pick up where it left off.

Write a handoff note in the shared file

The finishing agent appends a handoff note to AGENTS.md with the changes made, tests added, risks introduced, and decisions taken. The next agent reads this note and can review the changes or take over the task if needed. The note also serves as documentation for future reference.

The shared file approach works for small tasks, but it doesn’t enforce completeness. An agent can forget to include tests or risks, or the file can become stale. A more dependable pattern is to use the MCP server’s handoff tool, which enforces a structured handoff and marks the task review-ready automatically.

Call the MCP server’s handoff tool

An agent calls handoff with the changes, tests, risks, and decisions. The server records the handoff, marks the task review-ready, and surfaces the evidence to the other agent. The other agent can then call get_task_context to see the full context before it starts reviewing.

The MCP server’s handoff tool ensures a clean handoff by enforcing structure and marking the task review-ready. It also keeps a record of all handoffs, so you can audit decisions or revisit tasks later. The tool is the same whether you use the local server or a team instance.

The MCP server turns intent and progress into live, shareable state that both agents read and write in real time, so coordination happens before edits, not after.

If you coordinate two agents with nothing but a branch and a shared file, you will still see merge conflicts and stale context. The only way to prevent that is to centralize state in a single place both agents call before they start editing, while they work, and before they hand off. The five tools are the interface to that state, and they work the same whether you run the server locally or deploy it to a team machine. For a deeper look at which agents support MCP, see the list of supported coding agents.