markus41/plugins/claude-code-expert/skills/checkpointing

Checkpointing

Track, rewind, and summarize Claude's edits and conversation to manage session state. Built-in feature — no configuration required.

Overview

Claude Code automatically tracks file edits as you work, allowing you to quickly undo changes and rewind to previous states. This safety net lets you pursue ambitious, wide-scale tasks knowing you can always return to a prior code state.

How Checkpoints Work

Automatic Tracking

• Every user prompt creates a new checkpoint
• Checkpoints persist across sessions (available in resumed conversations)
• Auto-cleaned after 30 days (configurable)
• Tracks all changes made by Claude's file editing tools

Rewind Menu

Open with Esc + Esc (double-press) or /rewind command.

Scrollable list shows each prompt from the session. Select a point and choose an action:

| Action | Effect | |:-------|:-------| | Restore code and conversation | Revert both code and conversation to that point | | Restore conversation | Rewind to that message, keep current code | | Restore code | Revert file changes, keep conversation | | Summarize from here | Compress conversation from this point forward | | Never mind | Cancel, return to message list |

After restoring conversation or summarizing, the original prompt is restored into the input field for re-sending or editing.

Restore vs Summarize

Restore (3 options) — reverts state: undoes code changes, conversation history, or both.

Summarize from here — different behavior:

• Messages before selected point stay intact
• Selected message and all subsequent → replaced with compact AI summary
• No files on disk changed
• Original messages preserved in transcript (Claude can reference details)
• Like targeted /compact — keep early context in full, compress what's using space
• Optional instructions to guide summary focus

Use summarize to free context space. Use fork (claude --continue --fork-session) to branch and try a different approach while keeping original session.

Common Use Cases

• Exploring alternatives: Try different implementations without losing starting point
• Recovering from mistakes: Quickly undo changes that broke functionality
• Iterating on features: Experiment with variations, revert to working states
• Freeing context space: Summarize verbose debugging sessions from midpoint forward

Pipeline and Build Integration

Checkpointing is valuable during CI/CD workflows:

Failed Build Recovery

When a build fix attempt makes things worse, rewind to the pre-fix state and try a different approach.

Iterative Debugging

Checkpoint before each debugging hypothesis. If approach A fails, rewind and try approach B without residual changes.

Safe Refactoring

Make sweeping changes with confidence — rewind instantly if tests fail.

Limitations

Bash Commands Not Tracked

Files modified by bash commands (rm, mv, cp) are NOT tracked. Only direct file edits through Claude's editing tools.

External Changes Not Tracked

Manual changes outside Claude Code and edits from other concurrent sessions are normally not captured (unless they modify same files as current session).

Not a Version Control Replacement

• Use Git for commits, branches, long-term history
• Think of checkpoints as "local undo" and Git as "permanent history"
• Checkpoints complement but don't replace Git

Context Survival Pack — Resilience for Long-Running Work

For tasks that span multiple sessions or risk context loss from /compact, deploy this resilience system.

Active Task Summary File

Create .claude/active-task.md at the start of any long-running task:

# Active Task

**Started:** {date}
**Goal:** {one-sentence goal}
**Branch:** {branch name}

## Current Phase
{phase name + what's being done right now}

## Completed Phases
- [x] Phase 1: {description} — {outcome}
- [ ] Phase 2: {current}

## Modified Files
- `src/auth/middleware.ts` — added token refresh logic
- `src/auth/types.ts` — added RefreshToken type

## Verification Ledger
| File | Test | Status |
|------|------|--------|
| auth/middleware.ts | auth.test.ts | PASS |
| auth/types.ts | N/A (types only) | N/A |

## Next Action
{exact next step, specific enough to resume without context}

## Restart Prompt
If this session is lost, start the next session with:
"Continue the auth token refresh implementation. Read .claude/active-task.md first."

Post-Compact Restoration Hook

Register this hook to re-inject task state after /compact runs:

#!/usr/bin/env bash
# .claude/hooks/post-compact-restore.sh
# Registered on: PreCompact or UserPromptSubmit
set -euo pipefail

TASK_FILE=".claude/active-task.md"
if [ -f "$TASK_FILE" ]; then
  echo "=== ACTIVE TASK CONTEXT ===" >&2
  head -30 "$TASK_FILE" >&2
  echo "=== END ACTIVE TASK ===" >&2
fi

echo '{"decision": "approve"}'

Verification Ledger Protocol

Before compacting or ending a session, update the verification ledger in active-task.md:

# Quick ledger update command
for file in $(git diff --name-only HEAD); do
  echo "- \`$file\` — {purpose} — {test status}"
done

Session Restart Prompt Template

When resuming after compaction or restart:

Continue where we left off. Before doing anything else:
1. Read .claude/active-task.md
2. Check git log --oneline -5 to see what was committed
3. Run {test_cmd} to verify current state
4. Report: what phase are we in? What is the exact next step?
Then continue.

When to Create vs. Update active-task.md

| Event | Action | |-------|--------| | Starting a task > 30 min estimated | Create active-task.md | | Completing a phase | Update Completed Phases | | Writing or modifying a file | Add to Modified Files | | Running tests | Update Verification Ledger | | About to run /compact | Update Next Action | | Session about to end | Update Restart Prompt | | Task complete | Delete active-task.md |

See Also

• Interactive Mode — Keyboard shortcuts and session controls
• Built-in Commands — /rewind command reference
• CLI Reference — Command-line options