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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
# 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**
```bash
# Instant undo for mistakes
> Accidentally deleted important function
ESC ESC → Restore immediately
```

✅ **Comparing Approaches**
```bash
# Systematically evaluate options
1. Implement option A, note pros/cons
2. Rewind
3. Implement option B, note pros/cons
4. Choose winner
```

✅ **Safe Learning**
```bash
# 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**
```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
# 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**
```bash
# 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](https://docs.claude.com/en/docs/claude-code/checkpointing)
- [CLI Reference](https://docs.claude.com/en/docs/claude-code/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.