Agent Relay

Watch & Metrics

Agent Relay records every turn to disk as it happens. That makes two things easy: watching an active session from another shell, and rolling up token cost across an entire chain of handoffs after the fact. Both are local, both work without any background daemon.

Watch — live session observation

agent-relay watch streams the active session in the current repo. It reads from disk as new turn artifacts are written, so it works whether your agent-relay run is in a parent shell, a tmux pane, or a CI job.

terminal
agent-relay watch

What you'll see (one line per event):

  • turn 1 prompt sent 1,420 tokens
  • turn 1 output returned 380 tokens · 2 tool calls
  • turn 2 prompt sent 1,890 tokens
  • turn 2 decision switched to pytest
  • turn 3 blocker test_refresh_flow still red
  • status rate-limit reached · checkpoint saved

Decisions and blockers come straight from the same fields that end up in resume.json, so the watcher is also a live preview of what the handoff packet will contain.

Metrics — token and cost rollup

agent-relay metrics walks the local session store and prints a rollup. By default it reports the current repo's history:

terminal
agent-relay metrics

Output:

text
session                              agent        turns   tokens     cost     wall
─────────────────────────────────── ──────────── ─────── ───────── ──────── ──────
01J9X3M7K5VBHQEN6T2F4D8RPZ          claude-code     14    187,420   $1.41    12m
01J9X9N7Q2C5VFGMP4HTSXKDBE          codex            9    102,840   $0.78     6m
01J9XAEYR3D2BHQEN8T2F4D8RX          claude-code     17    214,950   $1.62    14m
─────────────────────────────────── ──────────── ─────── ───────── ──────── ──────
total                                                505,210   $3.81    32m

Cost is estimated from each provider's published per-token rates as of the time the session ran. The rate table ships with agent-relay-tool and is refreshed on agent-relay-tool upgrades — there is no network call at metrics time.

Common filters

terminal
agent-relay metrics --chain 01J9X3M7K5VBHQEN6T2F4D8RPZ

Walks the resume-packet links and only includes sessions that descend from the given start.

Why local-only matters

Both watch and metrics operate on files already on your disk. There is no telemetry, no third-party service, no API key required. If you delete .agent-relay/sessions/, the rollups disappear too — because the source of truth is your repo, not a vendor's database.

This is the same property that makes Agent Relay safe to use on private codebases without an enterprise procurement review.

Next

Sessions

The on-disk structure these tools read from.

Handoffs

The resume-packet contract decisions and blockers come from.