Run work in Agent Relay
Start day-to-day agent work in the no-args relay shell. It keeps one
repo-local session open, forwards normal prompts to the active agent, captures
observable output under .agent-relay/sessions/, and prepares handoff context
when you switch agents or hit a configured rate-limit trigger.
relayInside the shell, bare text goes to the active agent and slash commands control Relay:
/use claude
Fix the failing auth tests
/use codex
Continue from the current Relay session
/status
/metricsagent-relay run is the scriptable single-agent surface for CI, automation,
and one-off managed tasks. It creates the same kind of persisted session
artifacts, but it does not give you the long-lived interactive view, slash menu,
agent switching, or automatic REPL handoff flow.
Interactive workflow
cd /path/to/your/repo
relay install
relayrelay install wires local hooks and fallback order. relay opens the
interactive shell for the current repo.
Scriptable run synopsis
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 |
gemini | g | Gemini CLI |
opencode | o | OpenCode CLI |
Run /discover inside the shell, or agent-relay discover from scripts, to see
which adapters are installed on the current machine.
Scriptable run options
| Flag | Type | Default | Description |
|---|---|---|---|
--task, -t | string | — | Provide the task as a flag instead of a positional prompt. |
--continue | session id | — | Continue from an existing session id. |
--max-turns | int | 10 | Hard cap on turns before Agent Relay stops the session. |
--yes, -y | flag | false | Skip confirmation prompts. |
--json | flag | false | Emit machine-readable JSON. |
--quiet, -q | flag | false | Print only the minimum output. |
--repo | path | current directory | Run against a different repository path. |
Scriptable examples
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
run exits 0 after the managed command completes and writes its session
artifacts. Argument errors and agent launch failures surface through the root
CLI error path. Use --json when automation needs the session id, turn count,
and stop reason.