Guides

Fork & replay

checkpoint_fork is the "git branch" for agent runs. Copy any checkpoint into a brand-new thread, then run a different path from there, the original thread is never touched.

Why fork?

Agents make irreversible choices: a tool call, a model, a prompt strategy. When you want to compare two paths from the same starting point - A/B a planner, retry after a bad branch, or hand a known-good state to a different agent - you fork. Because every checkpoint is a content-addressed blob, forking is nearly free: it writes one new genesis checkpoint that points back at where it came from.

How it works

Fork loads the exact state at source_checkpoint_id, writes it as the genesis checkpoint of new_thread_id, and records a forked_from = "{source_thread}:{source_checkpoint}" lineage in the new thread's manifest. The new thread then evolves independently.

Genesis, not a copy of history

A fork creates a new thread whose first checkpoint equals the source state. It does not duplicate the source thread's entire history, the lineage pointer is enough to trace where it branched from.

Via the MCP tool

Any connected agent can fork with one call:

checkpoint_fork

checkpoint_fork(
  source_thread_id="run-42",
  source_checkpoint_id="0c3b84d1-…",
  new_thread_id="run-42-alt",
)

It returns the new genesis checkpoint and its lineage:

returns

{
  "source": "run-42:0c3b84d1-…",
  "new_thread_id": "run-42-alt",
  "checkpoint_id": "1f164ec0-…",
  "blob_id": "WL4TgZgqRE9Pwq1UEclzBJu89KFaaLe75p004_9gJyw",
  "forked_from": "run-42:0c3b84d1-…"
}

Via the Python API

python

from langgraph_checkpoint_walrus import WalrusSaver, WalrusClient

saver = WalrusSaver(WalrusClient())
result = saver.fork(
    source_thread_id="run-42",
    source_checkpoint_id="0c3b84d1-…",
    new_thread_id="run-42-alt",
)
print(result["forked_from"])  # run-42:0c3b84d1-…

The target thread must be empty

Fork refuses to write into a thread that already has checkpoints, that would overwrite real history. Pick a fresh new_thread_id. Loading a missing source checkpoint raises a clear error too.