agent-relay watch
Stream the active session line-by-line from another shell. The watcher reads artifacts as they're written to disk, so it works whether the run is happening in a parent terminal, a tmux pane, a CI job, or on a remote machine you've rsync'd the session directory from.
Synopsis
terminal
agent-relay watch [flags]Run from inside a repo with no flags to follow the most recent active session.
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--session | session id | latest active | Follow a specific session by ULID. |
--from | int | 0 | Start from a specific turn number. Useful when re-attaching to a long-running session. |
--filter | string | none | Only show events containing the substring. Repeatable. |
--no-color | flag | false | Disable ANSI colors. |
--json | flag | false | Emit one JSON event per line instead of formatted text. |
What you'll see
The watcher emits one line per event. Common event types:
| Type | Example |
|---|---|
prompt | turn 1 prompt sent 1,420 tokens |
output | turn 1 output returned 380 tokens · 2 tool calls |
tool | turn 2 tool run_tests · exit 1 |
decision | turn 2 decision switched to pytest |
blocker | turn 3 blocker test_refresh_flow still red |
status | status rate-limit reached · checkpoint saved |
Examples
Exit codes
| Code | Meaning |
|---|---|
0 | Watch stream ended cleanly (session completed or checkpointed). |
1 | The target session doesn't exist. |
130 | Interrupted with Ctrl-C (this is normal — the watcher has nothing to clean up). |