Reference

The eleven tools

Exposed over stdio by the tuskpoint-mcp server. Plus a twelfth helper, tuskpoint_info, that returns ready-to-paste client configuration so an agent can wire itself up.

Write

Persist, branch, roll back, or hand off a run.

PUTcheckpoint_save(thread_id, state_json)

Serialize agent state, gzip it, and store it as an immutable Walrus blob. Also writes a one-line summary to MemWal.

→ { checkpoint_id, blob_id, thread_id }

e.g. checkpoint_save("run-42", '{"step":"research","sources":["a","b"]}')

FORKcheckpoint_fork(source_thread, source_id, new_thread)

Git-branch an agent run. Copy any checkpoint into a new thread to replay a different path, the original stays untouched.

→ { new_thread_id, checkpoint_id, blob_id, forked_from }

e.g. checkpoint_fork("run-42", "0c3b84d1-…", "run-42-alt")

UNDOcheckpoint_rollback(thread_id, checkpoint_id)

Durable, auditable undo. Re-writes an earlier checkpoint's state as a new head of the same thread, append-only, so history (and the audit trail) stays intact.

→ { checkpoint_id, restored_from, blob_id, rolled_back_from }

e.g. checkpoint_rollback("run-42", "0c3b84d1-…")

HANDhandoff_checkpoint(thread_id, checkpoint_id, to_agent?)

Emit a tiny portable descriptor (blob id + SHA-256 + provenance) so another agent can adopt this exact state. No state is copied, only the Walrus pointer and its hash cross the boundary.

→ { source, blob_id, blob_sha256, to_agent }

e.g. handoff_checkpoint("run-42", "0c3b84d1-…", "agent-b")

ADOPTadopt_checkpoint(handoff_json, new_thread_id)

Adopt a handoff descriptor: re-fetch the blob from Walrus, verify its SHA-256 against the sender's, and write it as the genesis of a new thread. A tampered blob is rejected before it becomes state.

→ { adopted_from, new_thread_id, checkpoint_id, verified }

e.g. adopt_checkpoint(descriptor, "agent-b-run")

Read

Deterministic, content-addressed reads from Walrus.

GETcheckpoint_load(thread_id, checkpoint_id?)

Load a specific checkpoint by ID (or the latest). Deterministic, content-addressed read straight from Walrus.

→ { state, checkpoint_id, blob_id }

e.g. checkpoint_load("run-42", "0c3b84d1-…")

LScheckpoint_list(thread_id)

List every checkpoint for a thread, newest first, with lineage, timestamps, and summaries from the manifest.

→ { count, checkpoints[] }

e.g. checkpoint_list("run-42")

REScheckpoint_resume(thread_id)

Rehydrate the latest state so an agent can continue exactly where it left off after a crash.

→ { state, checkpoint_id }

e.g. checkpoint_resume("run-42")

DIFFcheckpoint_diff(thread_id, id_a, id_b)

Compare two checkpoints and report exactly what was added, removed, or changed between them.

→ { added, removed, changed, human_readable }

e.g. checkpoint_diff("run-42", id_a, id_b)

AUDITverify_trail(thread_id)

Audit a thread end-to-end. Re-fetches every content-addressed blob and recomputes its SHA-256, so tampering or corruption shows up as a FAIL step rather than a silent pass.

→ { ok, checkpoint_count, verified, tampered_count, steps[] }

e.g. verify_trail("run-42")

Discover

Find the right checkpoint in plain English.

FINDcheckpoint_search(query)

Ask a question in plain English. MemWal returns the nearest checkpoint summaries, pointers you then load exactly.

→ { results: [{ text, distance }] }

e.g. checkpoint_search("when did the writer start?")

tuskpoint_info

Calling tuskpoint_info returns the full tool list plus copy-paste MCP config for Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI, VS Code, Codex CLI, and the generic .mcp.json form, so an agent can discover how to connect without leaving the chat.