| 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
Every supported agent has its own resume path, and 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 four have a fork of their own; the rest resume the original session in place rather than branching from it:
| 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> |
| 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> |
catchup delegates to each agent's real command rather than reimplementing it, so this table tracks upstream: if an agent ships a fork, catchup gets it. Every agent can be read, searched, and used as either end of a fork --into handoff regardless of what its own resume can do — the column above only describes the same-agent path.
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:
Tool calls, command output, and reasoning traces are stripped, so what reaches the next agent is the discussion rather than a log of it. Because stdout is the wire format, the same transcript also crosses 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 supported agent 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, and Pi Agent have a fork of their own, so continuing leaves the original session untouched. Cursor, Cline, Kimi, and Antigravity have no fork upstream — catchup delegates to their resume, which picks the original session back up instead of branching from it. All eight can be either end of a cross-agent fork --into handoff.
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.