How to Hand Off Work Between Two AI Agents
To hand off work between two AI agents, write the state into shared plain text files, not into either agent's memory. One agent ends its shift by saving status, log, backlog, and open questions; the next agent reads those files and resumes. The handoff lives on disk, so it works across vendors and across a dead session.
Here is the insight that makes this easy: a handoff between two agents is the exact same problem as a handoff between two sessions of one agent. Both involve a worker who has no memory of what came before, arriving to continue work someone else started. Solve the session problem and you have already solved the multi-agent problem for free.
A clean handoff is a set of plain text files that hold the full working state, so any agent can read them and continue without asking a human what happened. The files are the shared brain. The agents are interchangeable readers of it. That is why this approach is model-agnostic: it does not matter whether the outgoing shift was Claude, GPT, or Gemini, and it does not matter whether the incoming agent is the same one an hour later or a different one entirely.
What must the file system contain for a clean handoff?
The file system must contain the current state, the recent history, the priority queue, and any open questions - each in a named file the next agent knows to read. In our own operation that is a small, fixed set: a state file (the single source of truth for where work stopped), a dated session log, a prioritized backlog, a mailbox for owner questions, and a metrics file. The incoming agent does not guess where to look; the reading order is fixed by protocol.
The incoming agent runs a 7-step start protocol before touching any work:
- Read the state file. Current state, where the last shift stopped, the concrete next steps.
- Read the latest session log. Context from the previous shift: what was tried, what failed.
- Read the backlog. The prioritized task list, so the agent picks the top unblocked item.
- Check the question mailbox. See whether the owner answered anything or unblocked a task.
- Glance at metrics. Note any new data on revenue or traffic that should change priorities.
- Recognize the session model. Match the work to the current agent's strengths; leave strategy-heavy tasks flagged for a stronger model if needed.
- Start work. Only now, with the full picture loaded, does the agent begin.
The outgoing agent runs a 5-step end protocol so those files are true when the next shift arrives:
- Update the state file: what is in progress, exactly where work stopped, the next three concrete steps.
- Append to the session log: what got done, what failed, what was learned today.
- Update the backlog: check off finished items, add new ones, reprioritize.
- Write open questions to the mailbox: anything that needs the owner, stated with what and why and how urgent.
- Commit: a single
git commitwith a descriptive message, so the whole state is versioned and recoverable.
Two protocols, roughly two minutes of reading and a few minutes of writing. That is the entire cost of making agents interchangeable. Read more on the persistent memory files that hold this state.
What breaks when you skip the protocol?
When you skip the protocol, the incoming agent starts blind and reinvents work the last shift already finished or already ruled out. Without a written state, it cannot know a niche was abandoned, a price was set, or a subagent's report was saved - so it repeats the decision, contradicts the previous one, or asks the owner a question the files should have answered.
The failure is quiet, which makes it dangerous. Nothing errors out. The agent produces confident, plausible work that simply duplicates or undoes the last session. You only notice when you read two logs that disagree, or find the same task done twice with different conclusions. Multiply that across daily shifts and the operation drifts instead of compounding.
The commit step is what makes the whole thing safe rather than fragile. Because every handoff ends in a commit, the state is versioned: if a session dies mid-edit or an agent corrupts a file, the previous good state is one git checkout away. That is also your audit trail - each commit records which shift changed what. The checkpoint habit is what turns a pile of text files into a handoff system you can trust.
FAQ
Do the two AI agents have to be from the same vendor?
No. The handoff lives in plain text files on disk, not in any vendor's memory, so the outgoing and incoming agents can be different models entirely. One shift can be Claude, the next GPT or Gemini. As long as each agent can read Markdown files and run the start and end protocols, the handoff works. That is the whole point of keeping state model-agnostic.
What about edit conflicts if agents run at the same time?
Run one agent at a time on a given project and there are no conflicts, because the handoff is sequential: one shift ends and commits before the next begins. If you must run agents in parallel, give each its own branch or its own set of files and merge deliberately. Shared mutable state plus simultaneous writers is how you get corruption, so most solo operators keep shifts serial.
How do I audit which agent did what?
Use the git history. Each end-of-session commit records the author and a descriptive message, so the log is a timestamped record of which shift changed which files and why. Set a distinct commit author per agent if you run several, and the blame view tells you exactly who wrote each line. The dated session logs give the human-readable version of the same trail.
Is a handoff between two sessions of one agent the same problem?
Yes, and that is why this scales. A session ending is just a handoff to a future agent with no memory of the present one. The same start and end protocols that let two different agents share a project let a single agent survive its own session dying. Build the file-based handoff once and it covers both cases at no extra cost.