Architecture

Agent Relay has three cooperating pieces:

1. Interactive REPL: the no-args relay shell that owns live agent processes, slash commands, handoffs, and session context.
2. Repo-local store: .agent-relay/, where turns, checkpoints, metrics, and resume packets are written for the current project.
3. Always-on daemon: ~/.relay/, where adapter events, snapshots, daemon config, and the IPC socket live.

Primary flow

The REPL keeps a long-lived RelayContext. Bare text goes to the active agent. Slash commands such as /status, /metrics, /race, and /use codex dispatch through the same command logic as the scriptable CLI.

When there is live context and the user switches agents, Relay prepares a handoff packet from the active session and starts the target agent with that context. Automatic rate-limit handoff uses the same path.

Storage roots

The REPL writes project work to .agent-relay/. The daemon writes machine-wide events and snapshots to ~/.relay/. They meet through the daemon IPC stream and handoff/resume translation.

REPL process model

relay with no subcommand enters the interactive shell:

• First-run onboarding detects agents and writes ~/.config/relay/config.toml.
• AgentRouter owns live agent sessions.
• Bare prompts are written to the active agent.
• Output is streamed, ANSI-sanitized, displayed, and persisted as turn artifacts.
• Older saved context can be auto-compacted after turns.
• /use <agent> routes through handoff when there is active context.
• The REPL subscribes to daemon handoff notifications when the daemon socket is available.

Daemon and adapters

Current shipped capture paths:

• Claude Code Notification hook installed by relay install.
• Codex Stop hook installed by relay install.
• Gemini CLI Notification hook installed by relay install.
• OpenCode event plugin installed by relay install.
• relay wrap <command> for generic CLI agents on POSIX.
• Optional relay proxy for provider response-header signals.
• relay mcp serve for MCP-aware clients; relay install --warp writes a Warp MCP snippet but does not silently edit Warp settings.

Some detected products are future adapter phases. Detection alone does not mean Relay has installed a capture integration for that product.

Proxy mode opt-in

Proxy mode is off by default. When explicitly enabled, it can observe provider rate-limit response headers such as anthropic-ratelimit-* and x-ratelimit-* and emit rate_limited or early-warning events. It requires the proxy extra and local certificate trust setup.

Where to look in the code