FoundryVTT/.claude/CHECKPOINTING_GUIDE.md

Claude Code Checkpointing Guide

Status: Feature Enabled (Built-in) Date: 2025-10-17

What is Checkpointing?

Claude Code automatically creates checkpoints before each file modification. Think of it as an "undo" system that lets you recover from unwanted changes without losing your work.

Key Features:

• ✅ Automatic checkpoint before every file edit
• ✅ Persists for 30 days
• ✅ Rewind conversation, code, or both
• ✅ Navigate forward and backward through history
• ❌ Tracks only Claude's direct file edits (not bash commands)

---

Quick Start

Accessing Checkpoints

# Method 1: Press Escape twice
ESC ESC

# Method 2: Use the rewind command
> /rewind

Three Rewind Options

When you access checkpoints, choose:

Option	What It Does	When to Use
Conversation Only	Reverts conversation, keeps code	Try different approaches without losing code
Code Only	Reverts files, keeps conversation	Code broke but conversation is useful
Both	Complete rollback	Need clean slate from specific point

---

Common Use Cases

1. Testing Different Implementations

Scenario: You want to compare different approaches

# Try approach A
> Implement authentication using JWT
[Code generated]

# Not satisfied? Rewind
ESC ESC
> Choose "Code Only"

# Try approach B
> Implement authentication using sessions
[Different implementation generated]

# Compare both, keep the better one

2. Recovering from Broken Code

Scenario: New changes broke the application

# Something broke
> The new changes broke the login feature

# Rewind to last working state
ESC ESC
> Choose "Code Only" to restore files
> Keep conversation to explain what broke

# Now fix the issue with better understanding
> Fix the login bug, this time check edge cases

3. Exploring Alternatives

Scenario: Want to see multiple solutions before deciding

# First implementation
> Implement caching with Redis
[Implementation complete]

# Explore alternative
ESC ESC
> Choose "Code Only"

# Second implementation
> Implement caching with in-memory LRU
[Different implementation]

# Compare performance, complexity, dependencies
# Choose best fit for your needs

4. Safe Refactoring

Scenario: Major refactoring with safety net

# Before refactoring
> Current state: 156 tests passing

# Make changes (checkpoints created automatically)
> Refactor authentication module to use dependency injection
[Large refactoring performed]

# Test the changes
> Run tests
[Some tests fail]

# Quick recovery
ESC ESC
> Choose "Code Only" to restore pre-refactor state
[All files restored, tests pass again]

# Try more careful approach
> Refactor authentication module incrementally, one class at a time

5. Learning & Experimentation

Scenario: Understanding different patterns

# See pattern A
> Show me observer pattern implementation
[Code generated]

# Understand it, then see alternative
ESC ESC
> Choose "Both" (start fresh)

# See pattern B
> Show me pub/sub pattern implementation
[Compare approaches]

# Choose which pattern fits your needs

---

What Checkpoints Track

✅ Tracked (Can Rewind)

• Write tool: New file creation
• Edit tool: File modifications
• All Claude Code file operations: Direct edits via tools

❌ Not Tracked (Cannot Rewind)

• Bash commands: rm, mv, cp, etc.
• Manual edits: Changes you make outside Claude Code
• Other sessions: Concurrent Claude Code sessions
• External tools: IDE edits, git operations

---

Best Practices

Use Checkpoints For

✅ Experimentation

# Try bold changes knowing you can rewind
> Completely redesign the API structure
# If it doesn't work out, rewind and try smaller changes

✅ Quick Recovery

# Instant undo for mistakes
> Accidentally deleted important function
ESC ESC → Restore immediately

✅ Comparing Approaches

# Systematically evaluate options
1. Implement option A, note pros/cons
2. Rewind
3. Implement option B, note pros/cons
4. Choose winner

✅ Safe Learning

# Explore without fear
> Try implementing this advanced pattern
# Don't understand it? Rewind and ask for explanation

Don't Replace Git With Checkpoints

❌ Not a Git Substitute

• Checkpoints expire after 30 days
• Not shared across team
• No branches or merging
• No remote backup

✅ Use Both Together

# Workflow:
1. Use checkpoints for experimentation
2. Find good solution via trial and error
3. Commit final version to git
4. Checkpoints remain as local undo buffer

❌ Don't Rely on Checkpoints for:

• Long-term history (use git)
• Team collaboration (use git)
• Production backups (use git + proper backups)
• Code review process (use git + PRs)

---

Checkpoint Workflows

Experimental Development Workflow

┌─────────────────────────────────────┐
│ 1. Start feature implementation     │
│    > Implement feature X             │
└──────────┬──────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 2. Checkpoint created automatically │
│    (happens behind the scenes)       │
└──────────┬──────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 3. Test the changes                  │
│    > Run tests                        │
└──────────┬──────────────────────────┘
           ↓
        ┌──┴──┐
        │ OK? │
        └──┬──┘
     Yes │  │ No
         │  └────────────┐
         ↓               ↓
┌──────────────┐  ┌──────────────────┐
│ 4a. Continue │  │ 4b. Rewind       │
│ Commit to git│  │ ESC ESC → Code   │
└──────────────┘  └────────┬─────────┘
                           ↓
                  ┌────────────────────┐
                  │ 5. Try alternative │
                  │ > Different approach│
                  └────────────────────┘

Safe Refactoring Workflow

Before Refactor
├─ Note current state
├─ Run tests (all passing)
└─ Begin refactoring
        ↓
During Refactor
├─ Checkpoints created automatically
├─ Make incremental changes
└─ Test frequently
        ↓
After Refactor
├─ Run full test suite
└─ If fails:
    ├─ ESC ESC → Rewind
    └─ Try more careful approach
  If passes:
    ├─ Review changes
    ├─ Commit to git
    └─ Done!

Learning & Comparison Workflow

Learning Phase
├─ Ask Claude to implement pattern A
├─ Study the implementation
├─ ESC ESC → Rewind (Code Only)
├─ Ask Claude to implement pattern B
├─ Compare both approaches
└─ Choose best fit

Implementation Phase
├─ Pick winning approach
├─ Refine if needed
├─ Test thoroughly
└─ Commit to git

---

Advanced Usage

Checkpoint Navigation

You're not limited to just rewinding - you can navigate through checkpoint history:

# Rewind to earlier point
ESC ESC
> Select checkpoint from history
> Choose rewind option

# Realize you went too far back
ESC ESC
> Navigate forward through checkpoints
> Restore to desired state

Selective Rewinding Strategy

When you have mixed changes:

# Made changes to 3 files: A.js, B.js, C.js
# Only C.js needs to be reverted

# Option 1: Rewind all, manually restore A.js and B.js
ESC ESC → Code Only
# Then manually recreate changes to A.js and B.js

# Option 2: Use git for selective revert (better)
> git checkout -- C.js  # Revert just C.js

Lesson: For selective file reversion, use git commands

Checkpoints Across Sessions

# Session 1 (morning)
> Implement feature X
[Checkpoints created]
# Close Claude Code

# Session 2 (afternoon)
> Continue with feature X
ESC ESC
# Can still access morning's checkpoints!
# Checkpoints persist across sessions

---

Troubleshooting

Common Issues

Q: "I pressed ESC ESC but nothing happened" A: Checkpoints might be empty if no file edits were made. Try after Claude modifies files.

Q: "Can I see a list of all checkpoints?" A: No, checkpoints are navigated interactively through the rewind interface. You browse them when you access ESC ESC or /rewind.

Q: "How far back can I rewind?" A: Up to 30 days of checkpoint history, depending on available storage and history.

Q: "Can I rewind specific files only?" A: No, code rewind affects all files modified since the checkpoint. For selective reversion, use git commands.

Q: "What if I rewind by mistake?" A: You can navigate forward through checkpoints. Rewinding doesn't delete checkpoint history - you can move both backward and forward.

Q: "Do checkpoints use a lot of disk space?" A: Claude Code manages storage automatically. Old checkpoints (30+ days) are cleaned up to free space.

Q: "Can my team access my checkpoints?" A: No, checkpoints are local to your machine and session. Use git for team collaboration.

Checkpoint Not Available

If checkpoints aren't working:

1. Verify file edits occurred

   • Checkpoints only created when Claude modifies files
   • Conversation-only sessions have no code checkpoints

2. Check Claude Code version

   • Checkpointing requires Claude Code 1.0+
   • Update if using older version

3. Storage issues

   • Check available disk space
   • Checkpoints may be limited if storage is low

4. Check logs

   • View .claude/logs/ for checkpoint-related messages
   • Look for errors during checkpoint creation

---

Integration with Git

Recommended Combined Workflow

# 1. Use checkpoints during active development
> Implement feature experimentally
[Try different approaches with checkpoints]

# 2. Once satisfied, commit to git
> Create commit with message
[Permanent history in git]

# 3. Checkpoints remain as local undo buffer
[Can still rewind recent changes if needed]

# 4. Push to remote
> git push
[Share with team, checkpoints stay local]

When to Use What

Situation	Use Checkpoints	Use Git
Trying different approaches	✅ Yes	❌ No
Quick undo of recent change	✅ Yes	⚠️ Maybe
Share with team	❌ No	✅ Yes
Long-term history	❌ No	✅ Yes
Branching/merging	❌ No	✅ Yes
Code review	❌ No	✅ Yes
Production deployment	❌ No	✅ Yes
Experimentation	✅ Yes	⚠️ Feature branches

Git + Checkpoints Best Practices

Pattern 1: Checkpoint for Micro-iterations, Git for Milestones

# Micro-iterations (checkpoints)
> Try implementation A
> Test
> ESC ESC → Rewind if needed
> Try implementation B
> Test

# Milestone (git)
> Implementation B works perfectly
> git commit -m "feat: implement feature X with approach B"

Pattern 2: Checkpoint for Safety, Git for History

# Before risky refactor
> git commit -m "wip: before refactoring"  # Git safety

# During refactor
> Refactor component
[Checkpoints created automatically]      # Checkpoint safety

# If refactor works
> git commit -m "refactor: improve component"  # Git history

# If refactor fails
ESC ESC → Rewind                              # Checkpoint recovery

---

Quick Reference

Keyboard Shortcuts

Action	Shortcut	Alternative
Open rewind menu	ESC ESC	/rewind
Navigate history	Arrow keys	(in rewind menu)
Select checkpoint	Enter	(in rewind menu)
Cancel	ESC	(in rewind menu)

Rewind Options Summary

Option	Conversation	Code	Use Case
Conversation Only	← Reverted	✓ Kept	Try different prompts, keep work
Code Only	✓ Kept	← Reverted	Code broke, keep discussion
Both	← Reverted	← Reverted	Fresh start from checkpoint

Checkpoint Lifecycle

File Edit → Checkpoint Created → 30 Days → Auto-Cleanup
                ↓
        Available for Rewind
                ↓
        Navigate via ESC ESC

---

Further Reading

Official Documentation

• Checkpointing Guide
• CLI Reference

Related Features

• Hooks: Run commands on events
• Output Styles: Change response format
• Git Integration: Version control commands

---

Feature Status: ✅ Enabled (Built-in) Retention Period: 30 days Last Updated: 2025-10-17

Remember: Checkpoints are your safety net for experimentation. Use them freely during development, but always commit important work to git for permanent history and team collaboration.