Agent Relay

Quickstart

Get a complete interactive Relay session working in five steps. Total time: about three minutes from a fresh install to your first handoff-ready session.

  1. Wire local hooks and fallback order

    Inside any git repo, let Relay install its local daemon, supported hooks, and automatic fallback order. This is idempotent.

    terminal
    relay install

    If Relay detects at least two supported agents, it persists a handoff order such as claude -> codex. Override it with relay install --handoff-order claude codex gemini opencode if you want a different chain.

  2. Start the interactive layer

    Run the no-args relay command. The first launch may ask which default agent to use and whether to wrap the shell in tmux.

    terminal
    relay

    Inside the shell, use /use claude, /use codex, /use gemini, or /use opencode to pick the active agent. Bare text goes to that agent and is persisted into the current Relay session.

  3. Send your first task

    Type a normal prompt without a slash:

    text
    Fix the failing auth tests

    Relay forwards it to the active agent, streams the response, and stores the prompt/output artifacts under .agent-relay/sessions/.

  4. Switch or hand off

    If you want to switch manually, use /use:

    text
    /use codex

    Relay prepares a handoff packet from the active session and starts the target with that context. If a configured hook reports a rate limit while the REPL is running, Relay can do the same handoff automatically using the configured fallback order.

  5. Inspect sessions and cost

    In the REPL, slash commands map to the same command logic as the scriptable CLI:

    text
    /status
/metrics

    Output is local-first. Session artifacts live in the repo; REPL preferences live under ~/.config/relay/; daemon events and snapshots live under ~/.relay/.

Next steps

Sessions

Understand the on-disk layout of .agent-relay/ and what each turn artifact contains.

Handoffs

Read the resume-packet schema and learn how the next agent picks up mid-task.

Watch & Metrics

Stream live sessions and roll up token + cost across the chain.

Run workflow

Start with the interactive shell, then use scriptable commands when needed.