Skip to Content
GuidesGit Checkpoints

Git Checkpoints

After each agent step that can change files, Shep takes a snapshot of the feature’s worktree. You can then see exactly what one step changed, compare any two steps, and roll the worktree back to an earlier step if a later one went the wrong way.

Checkpoints are automatic. There’s nothing to turn on.

What gets a checkpoint

WorkflowSteps that record a checkpoint
Spec-drivenanalyze, requirements, research, plan, implement, the repair steps, merge
Fast (the default)fast-implement, merge
Explorationprototype-generate
  • The first time one of these steps runs for a feature, Shep records a baseline of the worktree as it was before any agent touched it.
  • A checkpoint is recorded after the step even if the step failed or stopped at an approval gate, so partial work is kept.
  • If a step changed nothing, no checkpoint is recorded for it.
  • Steps that only read files (validation, memory extraction) don’t record one.
  • Recording a checkpoint never fails a run. If a snapshot can’t be taken, the agent log says so and the run carries on.

Each checkpoint is labelled with a sequence number and the step, for example 0000-baseline, 0001-analyze, 0003-implement, 0004-repair_research in spec-driven mode, or 0001-fast-implement in fast mode.

Where they live

Checkpoints are commits under a hidden ref in your repository:

refs/shep/checkpoints/<feature-id>/0000-baseline refs/shep/checkpoints/<feature-id>/0001-analyze refs/shep/checkpoints/<feature-id>/0003-implement
  • They are not branches or tags, so git branch and git log don’t show them, and git push never sends them. They stay on your machine.
  • Taking a snapshot doesn’t touch your branch, HEAD, the index or the working tree. It includes tracked and untracked files, and skips whatever .gitignore excludes.
  • They are deleted when the feature’s worktree is cleaned up after merge, and when the feature is deleted or archived.

List a feature’s checkpoints

shep feat checkpoints <id>

This prints each step with when it was taken, how many files it changed with lines added and removed, and its commit. <id> is a feature id or id prefix.

See what changed

shep feat diff <id> --to implement # what the implement step changed shep feat diff <id> --from plan --to merge # everything between two steps shep feat diff <id> --from 0 --to 5 --stat # only the list of changed files
OptionMeaning
--to <step>Required. The step to show
--from <step>The step to compare against. Default: the checkpoint just before --to, so you see what that one step changed
--statOnly list the changed files

A step can be given three ways: a sequence number (3), a step name (implement, meaning that step’s latest checkpoint), or a label (0003-implement). Renames are detected.

Roll the worktree back

shep feat restore <id> plan # back to the worktree after "plan" shep feat restore <id> 0000-baseline -f # back to the start, no prompt

Shep asks before restoring unless you pass -f / --force. A restore:

  1. Records a pre-restore checkpoint of the worktree as it is now. To undo the restore, restore that checkpoint; Shep prints the command.
  2. Makes the worktree’s files match the chosen checkpoint. Ignored files such as node_modules and .env are kept.

The branch doesn’t move and no commits are rewritten. The rollback is an ordinary change in the worktree that the next step commits, so nothing already pushed is touched.

A restore is refused when:

  • the agent is running (a run waiting at an approval gate is fine),
  • the feature doesn’t run in its own worktree, or
  • the worktree can’t be read, for example because it was removed.

In the web UI

Open a feature and pick the Checkpoints tab.

The Checkpoints tab in Per step mode: five checkpoints from 0000-baseline (marked START) to 0004-repair_research, each with its file count, lines added and removed, time and a restore button; below, the diff of the selected step showing the changed files and a hunk in src/login.ts

  • Per step shows what the selected step changed.
  • Compare adds From and To pickers to diff any two steps.
  • The restore button on a row opens a confirmation: “The worktree’s files are replaced with this checkpoint. The current state is saved as a new checkpoint first, and the branch and its commits are not changed.” When a restore isn’t possible, the button is disabled and says why.

See also