Agent Relay

Always-on

The always-on layer is the local daemon plus adapter hooks that turn provider rate-limit signals into Relay handoffs. It does not replace the interactive relay shell; it supports it.

The normal flow is:

terminal
relay install
relay

relay install wires what it can detect locally, starts or registers the daemon, and persists an automatic handoff order when at least two supported agents are present.

What Ships

Claude Code hook

Installs a Claude Code Notification hook. Relay inspects the hook payload and emits a rate_limited event only when it sees a known provider rate-limit string.

Codex Stop hook

Installs a Codex Stop hook. Relay scans the last assistant message, error/output fields, and transcript tail for OpenAI rate-limit signals.

Gemini Notification hook

Installs a Gemini CLI Notification hook. Relay scans notification payloads for Google quota and rate-limit signals.

OpenCode plugin

Installs a Relay-owned OpenCode plugin under the OpenCode config plugins directory. The plugin forwards selected events to relay hook opencode-event; Relay emits rate_limited only for known quota and rate-limit signals.

PTY wrapper

relay wrap <command> runs a CLI agent through a PTY and scans stdout for Anthropic, OpenAI, Google, and generic HTTP 429 rate-limit patterns.

Optional proxy

relay proxy can observe provider response headers when explicitly enabled. It is off by default and requires the proxy extra.

Automatic handoff triggers

Automatic handoff is driven by one normalized event: rate_limited.

That event can come from:

  • Claude Code hook payloads.
  • Codex Stop hook payloads.
  • Gemini Notification hook payloads.
  • OpenCode plugin session.error, message.updated, and session.status events.
  • Live REPL output detection.
  • relay wrap output detection.
  • The optional HTTPS proxy.

Relay currently recognizes provider strings such as RateLimitError, rate_limit_error, anthropic-ratelimit, rate_limit_exceeded, x-ratelimit, RESOURCE_EXHAUSTED, quota exceeded, HTTP 429, and 429 Too Many Requests.

For an automatic handoff to execute, the REPL must be running, the event must match the active Relay session/agent, and a fallback order must exist. relay install now tries to infer that order from detected Claude, Codex, Gemini, and OpenCode CLIs. Use this only when you want to override it:

terminal
relay install --handoff-order claude codex gemini opencode

What happens on detection

When the daemon ingests a rate_limited event:

  1. The session registry folds the event into current daemon state.
  2. The handoff engine writes a snapshot under ~/.relay/snapshots/.
  3. A desktop notification is attempted.
  4. Live REPL subscribers receive a tail.handoff notification.
  5. If the event matches the active REPL agent/session, Relay prepares and launches the next agent from the configured fallback order.

The daemon debounces repeated rate-limit events for the same session so retry storms do not create a pile of duplicate handoffs.

Verification

terminal
relay doctor
relay daemon status
relay daemon tail
relay snapshots
relay dashboard

Future adapters

Relay can detect some editor and terminal products that do not yet have shipped auto-capture adapters. Cursor, VS Code-family editors, Warp auto-registration, and aider-specific capture are tracked as later adapter phases. Today, use relay wrap for generic CLI agents and relay install --warp to generate the Warp MCP snippet you can paste into Warp's MCP settings.