agent-relay handoff
Force a checkpoint on the currently-active session. Agent Relay finalizes
the in-flight turn, writes resume.json, and prints the recommended
launch command for the next agent.
Use this when you want to manually switch agents mid-task — the
automatic trigger fires on rate-limit detection or --max-turns.
Synopsis
terminal
agent-relay handoff [flags]When run from inside a repo with no --session flag, the command targets
the most recent active session in .agent-relay/sessions/.
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--session | session id | latest active | Target a specific session by ULID instead of the most recent. |
--reason | string | manual | A short reason logged in resume.json → checkpoint_reason. |
--to | agent alias | none | Recommend a specific next agent. Affects the launch command Agent Relay prints. |
--no-launch | flag | false | Write the checkpoint but skip printing the next-agent launch command. |
Examples
terminal
agent-relay handoffWrites resume.json for the current session and prints something like:
text
✓ checkpoint saved · 14 turns · 187,420 tokens
→ agent-relay run x --resume "Continue from current state"What the checkpoint contains
The full schema lives in Handoffs.
At a glance: decisions, blockers, touched_files, validation_state,
and a recommended next_task summary.
Exit codes
| Code | Meaning |
|---|---|
0 | Checkpoint written successfully. |
1 | No active session found in the current repo. |
2 | A handoff was already written for this session (use --session <id> to overwrite explicitly). |