Checkpoints

Fred takes a shadow-git snapshot after every successful write tool. If a turn goes sideways, you can /restore <sha> and walk it back exactly. Doesn't touch your real git.

How it works

A bare git repo at ~/.dsc/checkpoints/<workspace-hash>.git mirrors your workspace state. After every successful str_replace, create_file, or write-flavored bash dispatch, Fred commits the affected files into the shadow repo. The shadow repo is independent of your real git state — your branch, staged changes, .gitignore are all unaffected.

The shadow repo lives outside your project tree on purpose. Your project never gains a nested .git, never has commits appended to its real history, and never sees the snapshot author. Snapshots are committed under a synthetic identity (dsc-checkpoint <checkpoint@dsc.local>) so even if anything ever escaped the shadow, it'd be obviously synthetic.

Read-only tools (view, grep, glob, repo_map, request_rule) don't trigger snapshots — there's nothing to record. A 50ms debounce skips snapshots when bursts of writes fire back-to-back, so a loop of ten str_replace calls in the same iteration produces one checkpoint, not ten.

Listing checkpoints

> /checkpoints

Shows the most-recent 20, newest first:

  a3f9c12  14:22:08  turn 5 · str_replace src/lib/pricing.ts
  9b1e0d8  14:21:51  turn 4 · create_file src/lib/format.ts
  4e7c3a1  14:20:33  turn 3 · str_replace src/app/page.tsx
  ...

SHA prefix, local timestamp, then the commit subject (which is auto-generated from the triggering tool call). Empty list when no write tools have run this session yet.

Restoring

> /restore a3f9c12

Requires y/N confirmation, then resets the workspace files to the checkpoint's state. The default answer is n; only an explicit y proceeds.

restore workspace to a3f9c12? this overwrites files on disk.
  proceed? (y/N): y
restored a3f9c12 (12 file(s) checked out).

After restore, your real git's git status will show the restored files as modified — the shadow checkout reverted them on disk, but your real git's index still reflects whatever was there before. That's intentional. Stage and commit (or discard) normally from there.

What gets checkpointed

Only files that were touched by tool calls. Files Fred never read or wrote are ignored; the shadow repo doesn't try to mirror your entire workspace from scratch. Specifically:

  • git add -A runs against the worktree on every snapshot, so any file Fred modified that turn is included.
  • The user's .gitignore is intentionally NOT honored — the shadow repo is a forensic recovery aid, not a "what I want to publish" snapshot. If you need exclusions, add them to info/exclude inside the shadow repo.
  • Nested .git directories (submodules, sub-repos) are temporarily renamed to .git_disabled for the duration of the snapshot, then restored — git refuses to add across a nested repo boundary, so this is the workaround.

Toggling

Set DSC_CHECKPOINTS=0 to disable globally. Useful for:

  • Monorepos where the shadow git is huge and the snapshot cost adds up.
  • CI runs where you don't need rollback.
  • Throwaway sessions on a branch you'd just git reset anyway.

Default is on — checkpoints are cheap until they're not, and the first time you hit "wait, what did the model just do" you'll want them.

vs. your real git

Checkpoints are deliberately not git-like in the ways that matter:

  • Not pushed anywhere.
  • Not branched — there's a single linear history per workspace.
  • Not part of your normal git workflow — you can't see them in your editor's git pane.
  • Not durable across machines — the shadow repos live in ~/.dsc/checkpoints/ on this machine only.

Think of them as session-local time travel. They give you a "rewind" button for a turn that went sideways, not a replacement for git commit.

Hygiene

Once a week, Fred prunes shadow repos whose workspace path no longer exists on disk (deleted projects, moved directories). The prune marker lives at ~/.dsc/checkpoints/.last_prune; failures are swallowed silently — this is hygiene, not a hot path.

If you want a manual cleanup, just delete ~/.dsc/checkpoints/ entirely. It'll regenerate on your next session, minus the history. Nothing else relies on it.

Note

Restoring is a workspace overwrite — anything you've changed in the editor since the checkpoint is gone unless you stage it first. The shadow checkout doesn't merge; it replaces.

Tip

Pair /checkpoints + /restore with plan mode. Plan first, act, checkpoint, verify; if something feels off, restore and replan. The shadow git turns "let's see what happens" into a low-stakes experiment.

Related

See /docs/slash-commands for the full /checkpoints + /restore surface and /docs/configuration for the rest of the ~/.dsc/ layout.