| Native resume | HANDOFF.md | Transcript handoff | |
|---|---|---|---|
| Keeps native session state | Yes | No | No |
| Works across different agents | No | Yes | Yes |
| Effort to produce | None | You write it | None |
| Completeness | Full | Only what you remembered | Whole conversation |
| Context cost in the target | None | Low | Proportional to the transcript |
| Works after the agent is closed | Usually | Yes | Yes |
Native resume — the default you should reach for first
When an agent has a CLI resume path, catchup delegates to it rather than reimplementing it:
Without --into, this is the agent's real resume, and what that means differs by agent. Only five have a fork of their own; most of the rest resume the original session in place rather than branching from it, and one has no CLI to resume from at all:
| Agent | <agent> | Same-agent fork | What it runs |
|---|---|---|---|
| Claude Code | claude | Forks — original untouched | claude --resume <id> --fork-session |
| Codex | codex | Forks — original untouched | codex fork <id> |
| OpenCode | opencode | Forks — original untouched | opencode --session <id> --fork |
| Pi Agent | pi-agent | Forks — original untouched | pi --fork <id> |
| Grok Build | grok | Forks — original untouched | grok --resume <id> --fork-session |
| Cursor | cursor | Resumes in place | cursor-agent --resume <id> |
| Cline | cline | Resumes in place | cline -i --id <id> |
| Kimi | kimi | Resumes in place | kimi --session <id> |
| Antigravity | agy | Resumes in place | agy --conversation <id> |
| Copilot CLI | copilot | Resumes in place | copilot --resume=<id> |
| DeepSeek Harness | deepseek | Resumes in place | dsh --profile tui --resume <id> |
| ZCode | zcode | No CLI to resume | Continue inside ZCode, or catchup fork zcode --into <agent> |
| Amp | amp | Local conversation source only | Native launch and resume unsupported |
catchup delegates to each agent's real command rather than reimplementing it, so this table tracks upstream. Every supported agent can supply a handoff. Amp reads only locally cached conversations and omits tool results and reasoning. Claude Code, Codex, Copilot CLI, Cursor, Cline, Antigravity, OpenCode, Pi Agent, and Grok Build can be launched as interactive --into targets.
If you are staying in one agent and it is still running, you do not need a tool. Use the agent's own resume. catchup is worth installing for the cases below — crossing agents, crossing machines, or not remembering which session held the work.
HANDOFF.md — a summary you write yourself
The common workaround: before switching, write a Markdown file describing where things stand, then paste it into the next agent. It is portable and short, and the act of writing forces you to decide what matters.
The costs are that it takes time exactly when you have least of it, and it can only contain what you thought to include. A decision made forty messages ago that turns out to matter is simply gone.
Transcript handoff — what catchup does
The conversation already exists on disk. Rendering it costs nothing:
A direct handoff includes the conversation and source-marked failed tool calls. Successful tool activity and reasoning traces stay out, so it is a briefing rather than a raw execution log. Because stdout is the wire format, a clean transcript can also cross machines:
The tradeoff is length. A transcript is bigger than a summary you would have written, which is why --since-compact and --last <N> exist.
Questions
When do I not need catchup at all?
When you are staying in the same agent and it has not stopped. Every CLI agent catchup reads ships its own resume, and using it directly is simpler. catchup earns its place when you are crossing agents, crossing machines, or cannot remember which session held the work.
Is a hand-written HANDOFF.md worse than a transcript?
Not worse, different. A summary you wrote is shorter and reflects your judgment about what mattered; a transcript is complete but longer and includes detail nobody needs. The transcript's advantage is that it costs nothing to produce and cannot forget something you did not think to write down.
Which agents can actually fork a session rather than resume it?
Claude Code, Codex, OpenCode, Pi Agent, and Grok Build have a fork of their own, so continuing leaves the original session untouched. Copilot CLI, Cursor, Cline, Kimi, Antigravity, and DeepSeek Harness resume in place. Native resume is unsupported for ZCode and Amp. All thirteen can supply a handoff; Claude Code, Codex, Copilot CLI, Cursor, Cline, Antigravity, OpenCode, Pi Agent, and Grok Build can be launched as interactive targets.
Can any tool move native session state between two different agents?
No. Agents store different things in incompatible formats, so nothing can reconstruct one agent's internal state inside another. Anything crossing agents carries a transcript. Only same-agent resume preserves real state.