Human-in-the-loop multi-agent collaboration using plain files.
AgentRelay is a lightweight protocol for using Claude and Codex together on the same project without losing context between sessions. Both agents start every session cold. AgentRelay fixes this with plain Markdown files as shared state.
The current owner writes the next agent's full task into a handoff file before stopping. The next agent reads the file and picks up where things left off.
One trigger passes the work forward:
HandOff: CLAUDE MyProject
HandOff: CODEX MyProject
Claude designs. Codex implements. The user decides. Files remember.
- Claude Code (CLI, desktop, or VSCode extension)
- GitHub Copilot or Codex agent in VS Code
- PowerShell 5.1 or newer (Windows)
- A local workspace folder
See docs/QUICKSTART.md for step-by-step setup.
The short version:
- Run the setup helper to scaffold a workspace and first project
- Fill in the first task in the project handoff file
- Send
HandOff: CLAUDE YourProjectNamein Claude Code
Three files carry the state:
| File | Purpose |
|---|---|
AGENT-HANDOFF.md at workspace root |
Protocol document and active project index |
AGENT-HANDOFF.md inside each project |
Live task board -- owner, task, files in scope, pending tasks |
CLAUDE.md / AGENTS.md |
Agent-specific role and read-order instructions |
The core rule: an agent never stops without writing the next agent's full context into the project handoff file. If it stops without doing this, the next agent starts cold and the workflow breaks.
| Folder | Contents |
|---|---|
templates/ |
Starter files for workspace and project handoffs |
tools/ |
PowerShell setup helper and handoff validators |
hooks/ |
Optional Claude Code hook scripts for session logging and file protection |
experiments/ |
Write-ups showing how the hooks were built and tested |
docs/ |
Full documentation and design notes |
| Doc | What it covers |
|---|---|
| docs/QUICKSTART.md | Setup in 8 steps |
| docs/AGENTRELAY-EXPLAINER.md | How it works and what makes it different |
| docs/AGENTRELAY-PROJECT-DOCUMENT.md | Full reference including comparison to other tools |
| docs/VALIDATION-CHECKLIST.md | Verify a setup is correct |
| docs/GLOBAL-ENFORCEMENT.md | How the protocol is enforced across agents |
MIT