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

Inside the interactive relay shell, run /watch to stream the active session:

text
/watch

From another shell — a tmux pane, a CI job, or a remote box — agent-relay watch does the same thing:

terminal
agent-relay watch

Either way it reads from disk as new turn artifacts are written, so it works whether the interactive relay shell is open in a parent terminal or a scriptable agent-relay run job is running in tmux or CI.

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 from the same captured state that feeds handoff packets, so the watcher is also a live preview of what the next agent will receive.

Metrics — token and cost rollup

Inside the interactive relay shell, run /metrics for the rollup:

text
/metrics

From another shell, agent-relay metrics walks the same local session store and prints it. 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

These run as slash commands in the relay shell. The same flags work on agent-relay metrics from another terminal.

text
/metrics 01J9X3M7K5VBHQEN6T2F4D8RPZ

Shows metrics for the selected session id.

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.