checkpoint

An undo button for agents. Snapshot a project's working tree before a risky change; if it goes wrong, restore it exactly. Git-independent, captures tracked and untracked files.

checkpoint("before refactor")   →  cp_lz9k_a1  (142 files)
… big multi-file edit …
verify()                        →  ok: false
restore("before refactor")      →  reverted everything, clean slate

Why

Agents make sweeping multi-file changes constantly, with no real undo. Git exists, but agents use it inconsistently and it doesn't cleanly capture untracked files. checkpoint is a dead-simple safety primitive: one call before, one call to roll back. It pairs with verify — checkpoint → edit → verify → restore if it broke.

Tools

• checkpoint(label?) — snapshot now; returns an id + label.
• restore(checkpoint) — make the working tree match a checkpoint exactly (revert modified, recreate deleted, remove created-since). Destructive by design.
• diff_checkpoint(checkpoint) — what changed since (added/modified/deleted), no restore.
• list_checkpoints() · drop_checkpoint(checkpoint)

How it works

Copies in-scope files into a store outside the project (~/.agent-checkpoints/<root>/<id>/) with a content-hash manifest. Restore is exact: it overlays the snapshot and removes anything created since. Excludes node_modules, .git, build dirs, and files > 5 MB.

Setup

npm install
npm test

claude mcp add checkpoint -e CHECKPOINT_ROOT=/path/to/project -- node /abs/path/checkpoint/dist/server.js
# or CLI: agent-checkpoint checkpoint "before X" | restore <id> | diff <id> | list

Honest limits

• Copy-based, so a checkpoint is a full snapshot of in-scope files (fine for source trees; excludes the heavy dirs). Not deduplicated across checkpoints.
• restore is destructive on purpose — it removes files created since the checkpoint. That's the point, but know it before calling.
• Empty directories left by removed files aren't pruned.