Every AI session starts from zero. No memory of what was built last week. No record of decisions made. No context about which files are in scope, what is already done, or what comes next.
For a one-off task that is fine. For ongoing project work, especially complex infrastructure work, it is a real productivity problem. Every session starts with a context rebuild that can take several minutes before any useful work happens. Across dozens of active projects, that adds up quickly.
AgentRelay was built to solve this. Not a framework. Not an orchestration layer. A small set of plain Markdown files that any agent can read, regardless of which tool runs it.
The core insight
The whole system starts from one observation: file-based state is shared memory. If it is not written in a file, the next agent does not know it.
Chat history disappears when a session ends. Files do not. Any agent in any session can read a file. Files can be version-controlled, backed up, and read by humans too. That is the foundation everything else is built on.
How it works
Each project gets a small set of files:
- AGENT-HANDOFF.md: the live task board. Current owner, next action, files in scope, files off limits, acceptance criteria.
- CLAUDE.md: Claude reads this automatically. Holds role instructions and design context for this project.
- AGENTS.md: Codex reads this automatically. Same idea.
- DECISIONS.md: durable decisions both agents must respect. Once logged, not revisited without explicit approval.
At the workspace level, one more AGENT-HANDOFF.md acts as the index across all active projects. It tracks which project is currently active and who owns it.
The handoff trigger is one word:
When sent, the receiving agent walks up the directory tree to find the workspace root, reads the Active Handoff table, finds the current project, reads that project's handoff file, checks ownership, and picks up the next unchecked task. No long prompts. No context re-paste.
Explicit routing is also supported when needed:
This switches the active project and assigns it to the named agent in a single line.
The task lifecycle
Claude and Codex are good at different things. Claude works well with broad context: design, architecture, reasoning across many files, tradeoff decisions. Codex works well with focused tasks: exact file edits, command execution, verification, testing.
AgentRelay routes work based on that difference. A typical cycle looks like this:
- User describes what needs to be built
- Claude reads the workspace and project handoff, does the design work, writes the full implementation spec into Pending Tasks, sets Current Owner to Codex
- User opens Codex, sends
HANDOFF - Codex reads the spec, implements the design, writes findings to CODEX_REVIEW.md, sets owner back to User
- User reviews and approves
The rule that holds this together: an agent never stops without writing the next agent's full context into the project handoff file and updating the owner. That discipline is what the whole workflow depends on.
What makes it different
Most multi-agent tools fall into one of two categories: full orchestration frameworks (CrewAI, LangGraph, AutoGen) that require code to wire agents together, or single-tool solutions where "multi-agent" means different modes inside one product.
AgentRelay is neither. Claude and Codex are separate tools running in separate sessions. They share the same file-based state. There is no orchestration layer to write. There is no agent application to build. The protocol is a Markdown file and a single trigger word.
Four things that matter in practice:
- One word to continue work. Send
HANDOFFand the system finds the workspace, finds the active project, checks ownership, and proceeds. No context re-pasting. - Human stays in the loop by design. Every handoff requires a deliberate user action. No autonomous agent loops. Work moves only when the user decides it should.
- State survives the session. Coming back to a project after two weeks means reading the handoff file. The next step is right there. Chat history is gone but the file-based context is not.
- Work routes by agent strength. The protocol assigns work based on what each agent is actually good at, not by habit or convenience.
How it holds up in practice
AgentRelay has been running on real automation work across 28 active projects. The failure mode is predictable: an agent that stops mid-task without updating the handoff file leaves the next agent with broken context and no way to detect it. A Stop hook that checks whether the handoff file was updated before a session ends catches the most common version of this.
The system is also useful outside of multi-agent workflows. Returning to any project after a break means reading one file instead of reconstructing context from scratch. For long-running projects spanning many sessions, that is worth as much as the agent collaboration itself.
The full source is on GitHub: protocol templates, PowerShell setup helper, handoff validators, hook scripts, and documented experiments. Other projects from this workspace are on my GitHub profile.