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.