Skip to main content
Mibyan can automatically snapshot your project before destructive operations and restore it with a single command. Checkpoints are opt-in as of v2 — most users never use /rollback, and the shadow-store storage is non-trivial over time, so the default is off. Enable checkpoints per-session with --checkpoints:
Or enable globally in ~/.mibyan/config.yaml:
This safety net is powered by an internal Checkpoint Manager that keeps a single shared shadow git repository under ~/.mibyan/checkpoints/store/ — your real project .git is never touched. Every project the agent works in shares the same store, so git’s content-addressable object DB deduplicates across projects and across turns.

​
What Triggers a Checkpoint

Checkpoints are taken automatically before:
  • File tools — write_file and patch
  • Destructive terminal commands — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, output redirects (>), and git reset/clean/checkout
The agent creates at most one checkpoint per directory per turn, so long-running sessions don’t spam snapshots.

​
Quick Reference

In-session slash commands: CLI for inspecting and managing the store outside a session:

​
How Checkpoints Work

At a high level:
  • Mibyan detects when tools are about to modify files in your working tree.
  • Once per conversation turn (per directory), it:
    • Resolves a reasonable project root for the file.
    • Initialises or reuses the single shared shadow store at ~/.mibyan/checkpoints/store/.
    • Stages into a per-project index, builds a tree, and commits to a per-project ref (refs/mibyan/<project-hash>).
  • These per-project refs form a checkpoint history that you can inspect and restore via /rollback.

​
Configuration

Configure in ~/.mibyan/config.yaml:
To disable everything:
When enabled: false, the Checkpoint Manager is a no-op and never attempts git operations. When auto_prune: false, the store grows until you run mibyan checkpoints prune manually.

​
Listing Checkpoints

From a CLI session:
Mibyan responds with a formatted list showing change statistics:

​
Inspecting the Store from the Shell

Sample output:
Force a full sweep (ignores the 24h idempotency marker):

​
Previewing Changes with /rollback diff

Before committing to a restore, preview what has changed since a checkpoint:
This shows a git diff stat summary followed by the actual diff.

​
Restoring with /rollback

Behind the scenes, Mibyan:
  1. Verifies the target commit exists in the shadow store.
  2. Takes a pre-rollback snapshot of the current state so you can “undo the undo” later.
  3. Restores tracked files in your working directory — preserving your hand-edits (see below).
  4. Undoes the last conversation turn so the agent’s context matches the restored filesystem state.

​
User hand-edits are preserved by default

/rollback <N> restores only the files Mibyan itself changed. Every successful write_file / patch records the file’s content hash in an agent-write ledger; at restore time, any file whose current contents no longer match what Mibyan last wrote (you edited it afterwards, or Mibyan never touched it) is skipped instead of overwritten, and listed in the output:
To force the classic full restore that reverts everything — including your own edits — add --all:
If the ledger is empty (a store created before this feature, or Mibyan hasn’t written any files in the project yet), /rollback falls back to the full restore automatically.

​
Single-File Restore

Restore just one file from a checkpoint without affecting the rest of the directory:

​
Safety and Performance Guards

​
Nested Git repositories

A checkpoint of a parent directory can store a nested repository as a Git gitlink (a commit reference), not a copy of its files. Recursive capture of nested repositories is not supported: their uncommitted edits and untracked files are not recoverable from that parent checkpoint. Checkpoints taken by this version or later are labelled in /rollback listings, for example before write_file: app.py [nested git repos not captured: tool]. If the selected checkpoint contains gitlinks, a full rollback (including --all) is refused before changing files or creating a pre-rollback snapshot. Selecting a nested repository, a file below it, or a Git pathspec matching it also refuses the restore rather than reporting success for uncaptured files. You can still restore unrelated captured files, for example /rollback 1 notes.txt. Keep separate backups or checkpoints taken directly from the nested repository’s own working directory.

​
Container Backends

With a container terminal backend (docker, singularity, modal, daytona, vercel_sandbox, or a container plugin), file paths belong to the sandbox rather than the host. Mibyan therefore does not take checkpoints or record the agent-write ledger for those paths, and /rollback explains the limitation: it still lists existing host checkpoints but refuses diff and restore, on the CLI and in messaging-gateway chats alike; /diff session answers with the same reason. The TUI and Desktop behave the same: /rollback list still works while /rollback diff and /rollback <N> are refused with that reason. Local and SSH backends are unaffected. To point terminal.cwd at the container-side view of a mounted directory see terminal.docker_mount_cwd_to_workspace.
  • Git availability — if git is not found on PATH, checkpoints are transparently disabled.
  • Directory scope — Mibyan skips overly broad directories (root /, home $HOME).
  • Repository size — directories with more than 50,000 files are skipped.
  • Per-file size cap — files larger than max_file_size_mb (default 10 MB) are excluded from the snapshot. Prevents accidentally swallowing datasets, model weights, or generated media.
  • Total store size cap — when the store exceeds max_total_size_mb (default 500 MB), the oldest commit per project is dropped round-robin. Each drop is reclaimed before deciding whether another is necessary. Every project keeps at least one snapshot. A failed Git operation stops pruning and is reported; maintenance never discards more history to compensate for failed reclamation.
  • Real pruning, off the hot path — max_snapshots and the size cap are enforced by rewriting the per-project ref at checkpoint time (cheap); the store is then marked .gc-pending and the periodic prune runs git gc --prune=now once, so loose objects don’t accumulate and a tool call never waits on a full repack.
  • Concurrent operations — snapshots, restores, diffs and maintenance use one process-shared store lock. An operation reports a busy store rather than running GC over another process’s unpublished objects. A restore applies its selected tree before pruning the safety snapshot’s history.
  • No-change snapshots — if there are no changes since the last snapshot, the checkpoint is skipped.
  • Non-fatal errors — snapshot failures do not block your tools. Pruning failures are logged as warnings; explicit maintenance reports an error count.

​
Where Checkpoints Live

Each <hash> is derived from the absolute path of the working directory. You normally never need to touch these manually — use mibyan checkpoints status / prune / clear instead. The sibling .checkpoints.lock coordinates processes and survives a store clear. Do not remove it while Mibyan is running.

​
Migration from v1

Before the v2 rewrite, each working directory got its own complete shadow git repo directly under ~/.mibyan/checkpoints/<hash>/. That layout couldn’t dedup objects across projects and had a documented no-op pruner — the store would grow without bound. On first v2 run, any pre-v2 shadow repos are moved into ~/.mibyan/checkpoints/legacy-<timestamp>/ so the new single-store layout starts clean. Old /rollback history is still reachable by manually inspecting the legacy archive with git; once you’re confident you don’t need it, run:
to reclaim the space. Legacy archives are also swept by auto_prune after retention_days.

​
Best Practices

  • Enable checkpoints only when you need them — mibyan chat --checkpoints or per-profile enabled: true.
  • Use /rollback diff before restoring — preview what will change to pick the right checkpoint.
  • Use /rollback instead of git reset when you want to undo agent-driven changes only.
  • Check mibyan checkpoints status occasionally if you use checkpoints regularly — shows which projects are active and what the store costs you.
  • Combine with Git worktrees for maximum safety — keep each Mibyan session in its own worktree/branch, with checkpoints as an extra layer.
For running multiple agents in parallel on the same repo, see the guide on Git worktrees.