agent-relay run
Start a new managed session — capture every turn, decision, and tool call
under .agent-relay/sessions/ while the agent works on the task you give it.
Synopsis
terminal
agent-relay run <agent> "<prompt>" [flags]<agent> is the adapter name or one of its built-in aliases:
| Adapter | Alias | Backed by |
|---|---|---|
claude-code | c | Claude Code CLI |
codex | x | OpenAI Codex CLI |
Run agent-relay discover to see which adapters are installed on the
current machine.
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--max-turns | int | unlimited | Hard cap on turns before Agent Relay stops the session. |
--resume | flag | false | Start by reading the latest resume.json in the repo and feeding it to the agent as context. |
--from | session id | latest | When combined with --resume, pick a specific session to resume from. |
--watch | flag | false | Open a live watcher in the same terminal — equivalent to agent-relay watch in another shell. |
--no-color | flag | false | Disable ANSI colors in Agent Relay's own output (the agent's output is untouched). |
--config | path | .agent-relay/config.toml | Override the config file path. |
Examples
terminal
agent-relay run c "Fix the failing auth tests"Starts a Claude Code session on the current repo. Captures every turn
to .agent-relay/sessions/<id>/turns/.
Exit codes
| Code | Meaning |
|---|---|
0 | Session completed cleanly. |
1 | Session ended in an unrecoverable error (see meta.json → error). |
2 | Session checkpointed for handoff (rate limit, manual stop, --max-turns reached). A resume.json is on disk. |
127 | The requested agent adapter is not installed. Run agent-relay discover. |