What is agent-relay?
agent-relay coordinates coding sessions from different AI vendors, passing work between a leader and a follower while leaving people in control of decisions. It is a prototype for developers who want tools such as Codex and Claude Code to plan, implement, or review work together without manually copying context between terminals. The project runs on macOS with Python 3.11 or newer, and supports extending agent coverage through adapters.
agent-relay Features:
Cross-Vendor Handoffs: A leader and follower exchange turns through a controller, which passes each session's work to the other.
Turn Limits: Set a handoff budget and per-turn timeout to bound a session, while recognizing that activity inside a turn is not visible to the relay.
Human Decisions: The relay pauses when a session needs your decision and waits for your answer before continuing.
Web Console: View session activity, manage pairings, and start or pause work from a console that listens on loopback.
Durable Records: Messages and decisions are stored on disk as hash-chained records that can be replayed or rebuilt.
Client Adapters: Adapters connect the relay to agent clients, with live-session coordination tested with Claude Code and Codex.
agent-relay Benefits:
Less Context Copying: Automatic handoffs reduce the manual effort of transferring plans, results, and reviews between separate terminals.
Human Oversight: Work can proceed between agents while questions that need your judgment remain visible as stopping points.
Bounded Work: Turn budgets and timeouts give you explicit limits for delegated tasks, rather than leaving a relay running without a defined boundary.
Traceable Work: Persistent message and decision records make it easier to inspect how agents reached a result after a run.
Clearer Monitoring: The console summarizes what a managed session is doing, helping you check progress without following every turn in a terminal.
Use Cases:
Plan and Build: Have Codex prepare a plan and review the result while Claude Code implements the changes, with the relay passing turns between them.
Review Every Change: Ask one coding model to critique another model's proposed work before you inspect the change yourself.
Bounded Test Fixes: Delegate a task such as fixing failing tests in a specific folder, with a maximum number of turns and a timeout for each turn.
Decision-Driven Tasks: Run a coding task that should pause for your input when an agent raises a question instead of continuing without your decision.
Agent Run Audits: Replay a completed thread to review the messages and decisions exchanged during a coordinated coding session.

