Handoff to another agent
Inside the interactive shell, use /use for the normal handoff path:
/use codex
/use claude
/use gemini
/use opencode/use is the most ergonomic REPL path. If there is live context, Relay routes
the switch through the same handoff machinery before activating the target.
The scriptable handoff surface is the target agent command:
agent-relay codex --task "Continue from the current state"
agent-relay claude --task "Review the Codex changes"
agent-relay gemini --task "Audit this plan"
agent-relay opencode --task "Finish the integration pass"The slash equivalents are available when you want to force a packet without changing the active agent:
/relay codex
/handoff codexSynopsis
agent-relay <agent> [flags]<agent> is one of claude, codex, gemini, or opencode, plus any
configured alias accepted by the agent resolver.
Options
| Flag | Type | Description |
|---|---|---|
--from | agent | Source agent, inferred when omitted. |
--task, -t | string | What the target agent should do next. |
--planning-note | string | Extra planning context to preserve. |
--planning-note-file | path | Read planning context from a file. |
--proposed-edits | string | Proposed edits that are not yet applied. |
--proposed-edits-file | path | Read proposed edits or a diff from a file. |
--no-launch | flag | Prepare the packet without launching the target. |
--no-auto-compact | flag | Skip the pre-handoff compaction sweep. |
--yes, -y | flag | Skip confirmation prompts. |
--repo | path | Repository path; defaults to the current directory. |
Examples
agent-relay codex --task "Continue the release prep"Captures the current observable repo/session state and prepares Codex to continue.
Automatic handoff
When relay install wires hooks and the REPL is running, rate-limit events can
trigger the same handoff path automatically. The fallback order is stored in
~/.config/relay/config.toml under [handoff].order and can be set with:
relay install --handoff-order claude codex gemini opencode