Share context between AI coding agents

You want two coding agents to finish one task without duplicating work or missing context. Git shares code, but not who is editing what, what you tried and rejected, which assumptions are still in play, or why a decision was made. You need a shared work-state that agents can read and update while they work.

Decide what context belongs in the shared state

Repository context is what Git already gives you: the files, branches, and history. Work context is everything else that matters to the task but does not belong in Git. Name the pieces you will persist so agents and reviewers can rely on them.

• Task ownership and who is currently editing which files
• Decisions made, alternatives rejected, and the reasons behind them
• Assumptions that are still valid and those that have been invalidated
• Open questions and unresolved dependencies
• Prompt threads and agent replies that explain the work so far

If you skip any of these, agents will duplicate effort, make the same mistakes twice, or overwrite each other’s changes. Keep the shared state concise so it stays readable and agents can update it without a heavy ceremony.

Use a minimal JSON file

Create a file named workstate.json at the repo root. It holds the fields you need and nothing more. Agents read it before they start, append their updates, and commit the file when they finish a step.

{
  "task": "Implement user login flow with JWT",
  "owner": "alice",
  "files": ["auth/jwt.js", "routes/login.js"],
  "decisions": [
    {"what": "Use RS256 for JWT", "why": "Stronger than HS256 for server keys"}
  ],
  "assumptions": [
    "Database has a users table with email and password_hash"
  ],
  "questions": [
    "Should rate limiting be per IP or per user?"
  ],
  "version": 3
}

Each agent reads the file, runs its update, and writes a new version with a short explanation. The version number prevents accidental overwrites. Reviewers can inspect the file to see the full history of the task without reading every prompt.

Store context in an MCP server

If you prefer not to commit extra files, run a local MCP server that exposes a shared workspace. Agents call its tools to register their presence, log decisions, and transfer work. The server keeps the state in memory and can expose it via an API or a web UI for humans to inspect.

Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way. You can surface those warnings in the server’s UI so humans know when two agents are about to collide.

Set up the shared state in three steps

Pick one approach for your team: a JSON file in the repo or an MCP server. The file works for small teams and simple repos. The server scales to many agents and complex workflows.

1. 01Create the shared state file or start the MCP server. For a file, add it to .gitignore if you do not want it in history. For a server, install the CLI and run it locally so agents can connect.
2. 02Write a short procedure that tells agents how to read and update the state. Include examples of what to log and how to format decisions and assumptions.
3. 03Run a quick test with two agents on the same branch. Have the first agent claim a task, make a decision, and log it. Have the second agent read the file, see the decision, and avoid duplicating work.

After the test, tweak the procedure until agents can update the shared state without manual intervention. If you use an MCP server, expose a simple UI so humans can audit the state and intervene if needed.

Keep the state accurate while agents work

Agents forget to update the shared state unless you make it part of their workflow. Build the updates into the agents’ prompts or wrap them in a thin script that runs after each prompt completes.

1. 01Log every significant decision immediately after it is made. Include the reasoning so reviewers do not have to reconstruct it later.
2. 02Flag assumptions that change or are invalidated. If a database schema differs from the assumption, update the state so the next agent does not rely on the wrong schema.
3. 03Mark open questions as resolved or move them to a backlog. Do not leave stale questions in the file; they mislead agents and reviewers.
4. 04Rotate ownership explicitly. When an agent finishes its slice, it calls the transfer tool or writes the new owner into the file and increments the version.

If you use an MCP server, log updates through its tools so the state is always consistent. The server can also emit events that trigger human review when a task reaches a milestone or when two agents claim overlapping work.

Handle merge conflicts in the shared state

The shared state file or server state can become a merge conflict if two agents update it at the same time. Decide up front who wins and how to resolve the conflict.

• Use a lock: only one agent can write at a time. The lock is released when the agent finishes or crashes.
• Use a version number: agents must read the latest version before writing. If the version changed, abort and retry after reading the new state.
• Use a merge strategy: agents resolve conflicts by keeping both updates and adding a note explaining the merge. This works when updates are additive, like logging decisions.

If you use an MCP server, it can enforce the lock or versioning automatically. For a file-based approach, write a small script that agents run before and after updates to manage the lock and version.

Use the state at review time

When the task is ready for a pull request, the shared state is the single source of truth for reviewers. They do not need to read every prompt or scroll through chat logs.

1. 01Point reviewers to the shared state file or server UI. Ask them to verify that decisions and assumptions are still valid and that open questions are addressed.
2. 02Check that ownership transfers happened correctly. If a task changed hands, confirm the new owner understands the context left by the previous agent.
3. 03Compare the state to the diff. If the code does not match the logged decisions, ask the agent to update the state or explain the discrepancy.
4. 04Archive the state when the pull request merges. If the state is a file, move it to a history/ folder. If it is an MCP server, mark the task as done so the workspace clears it.

A clean shared state at review time reduces the time spent on code review and prevents mistakes from slipping through because reviewers lacked context.

The less reviewers have to reconstruct from prompts or memory, the faster and more accurate the review becomes.