Agent Relay

Quickstart

Get a complete agent handoff working in five steps. Total time: about three minutes from a fresh install to seeing your token rollup.

  1. Discover available agents

    Inside any git repo, ask Agent Relay what's available locally. This is a safe, read-only check.

    terminal
    agent-relay discover

    You should see a list of detected agents with their version and the path to the binary. If nothing shows up, install the agent you want (claude-code or codex) first and rerun this command.

  2. Start a managed session

    Kick off a real task with Claude Code. Agent Relay wraps the call, captures every turn (prompt, output, tool calls, decisions) under .agent-relay/sessions/, and prints session metadata as it goes.

    terminal
    agent-relay run c "Fix the failing auth tests"

    c is the short alias for claude-code. Use x for codex.

    Want to watch it work in another shell?

    Open a second terminal in the same repo and run:

    terminal
    agent-relay watch

    Live turns, tool calls, and decisions stream into the watcher as the session progresses — useful for supervising long-running work without tailing log files.

  3. Trigger a handoff

    When the first agent hits a rate limit (or whenever you want to switch horses), Agent Relay writes a structured checkpoint and prints the launch command for the next agent. Run it to continue:

    terminal
    agent-relay codex --task "Continue from current state"

    The new session reads the resume packet from disk — every decision, blocker, touched file, and validation status from the previous agent is handed off in full.

  4. Inspect the resume packet

    The handoff is just a file. You can read it, diff it, or check it into git if you want a permanent audit trail.

    terminal
    cat .agent-relay/sessions/$(ls -t .agent-relay/sessions | head -n1)/resume.json

    What you'll see: a JSON document with decisions, blockers, touched_files, and validation_state — the same data the next agent consumed at startup.

  5. See the cost

    Across every agent in the chain — token counts, estimated dollar cost, and total wall time:

    terminal
    agent-relay metrics

    Output is local-only. No telemetry, no upload — the rollup is computed from session artifacts on disk.

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.

Commands

Full reference for every Agent Relay subcommand.