checkpoint

name	checkpoint
description	Save and verify session state using git commits and a checkpoints log. Use before risky multi-file changes or after completing a significant implementation block.
command	/checkpoint
allowed-tools	["Bash","Read"]
user-invocable	true
auto-invoke	[{"when":"Significant code changes completed (3+ files modified and tests pass)","action":"Suggest /checkpoint create after implementation block"}]

/checkpoint — Save and Verify Session State

Save or verify a named checkpoint using git + .claude/checkpoints.log.

Usage

/checkpoint create [name]    — Save current state
/checkpoint verify [name]    — Compare current state to checkpoint
/checkpoint list             — Show recent checkpoints

Create Checkpoint

When create [name] is called:

1. Run /quality-gate quick check (black + pytest -x -q)
2. Create a git commit with the checkpoint name:

   git add -p   # stage only intended changes
   git commit -m "checkpoint: [name]"
   

3. Append to .claude/checkpoints.log:

   echo "$(date +%Y-%m-%d-%H:%M) | [name] | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
   

4. Report: CHECKPOINT CREATED: [name] @ [hash]

Verify Checkpoint

When verify [name] is called:

1. Read the checkpoint hash from .claude/checkpoints.log
2. Compare current state:

   git diff [hash]..HEAD --stat
   git diff [hash]..HEAD -- '*.py' | head -60
   

3. Report:

   CHECKPOINT COMPARISON: [name]
   ==============================
   Commits since: N
   Files changed: X added / Y modified / Z deleted
   Build: PASS / FAIL
   Tests: +N passed / -N failed
   

List Checkpoints

cat .claude/checkpoints.log | tail -20

Typical Workflow

/checkpoint create "before-p2a"
  → implement 5 skills + 3 commands
/checkpoint verify "before-p2a"
  → confirm only expected files changed
/checkpoint create "p2a-complete"

Arguments

• create [name]: name must be [a-z0-9-_]+, max 40 chars
• verify [name]: name from log, exact match
• list: no args — shows last 20 entries

Notes

• Checkpoints are git commits — they survive context compaction
• Use before risky multi-file changes (P2, P3 batches)
• Combine with strategic-compact: compact AFTER creating checkpoint