Replay a Claude Run
Continue or fork a stored Claude conversation from a checkpoint.
Claude can continue a persisted run at a supported message boundary. Configure the agent with a database and native transcript storage first, following Run Claude.
List checkpoints for a saved run:
curl "http://127.0.0.1:7777/agents/support-agent/runs/$RUN_ID/checkpoints?session_id=$SESSION_ID"Use a returned message_index to fork from that boundary:
curl -N -X POST "http://127.0.0.1:7777/agents/support-agent/runs/$RUN_ID/continue" \
-F "session_id=$SESSION_ID" \
-F "continue_from=$MESSAGE_INDEX" \
-F 'fork=true' \
-F 'stream=true' \
-F 'input=Using the results available so far, explain the next step. Do not call tools.'The input is the new instruction for the continuation. Wait for its terminal event and inspect its new run ID and fork lineage.
Use background=false for checkpoint forks and completed-run continuations. With background=true, harness continuations without an eligible paused durable ticket return 501 before execution, in both stream modes. No continuation starts after that refusal. Keep the foreground request or stream open; durable background checkpoint forks are not supported yet. The existing paused-ticket queue continuation path is a separate contract.
Choose a boundary
continue_from | Behavior |
|---|---|
end | Continue after the stored conversation. |
last_user | Replay from the last user turn. |
| A checkpoint's message index | Continue from the selected message boundary. |
0 with new input | Start a branch without the source transcript. |
Completed runs always fork, even when fork is omitted. This preserves the original result. For other runs, choose fork=true when the source should remain available unchanged. A checkpoint from an unrelated run or session is not interchangeable with the source run's boundary.
In Python, use agent.continue_run(...) or await agent.acontinue_run(...) with run_id, session_id, continue_from, fork and input. list_run_checkpoints(run) from agno.os.checkpoints lists boundaries locally.
Understand what replay restores
Replay selects conversation context. It does not rewind files or undo MCP operations. Continuing before a mutation can cause that mutation to happen again. To recover after a completed tool call, select the checkpoint after its result and explicitly ask the agent to use that stored result; still enforce idempotency in the tool service.
Nested subagent tools appear in history, but only supported top-level boundaries are replay checkpoints. Use the returned checkpoint list rather than guessing an index from the UI's tool count.
Codex does not support this exact step-replay contract. Its native thread resume and bounded-history recovery are described in Sessions and State.
See the Claude replay cookbooks for completed-run forks, background continuation, failed-tool recovery and subagent checkpoints.