claude-howto/08-checkpoints/README.md

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
</picture>

# Checkpoints and Rewind

Checkpoints allow you to save conversation state and rewind to previous points in your Claude Code session. This is invaluable for exploring different approaches, recovering from mistakes, or comparing alternative solutions.

## Overview

Checkpoints allow you to save conversation state and rewind to previous points, enabling safe experimentation and exploration of multiple approaches. They are snapshots of your conversation state, including:
- All messages exchanged
- File modifications made
- Tool usage history
- Session context

Checkpoints are invaluable when exploring different approaches, recovering from mistakes, or comparing alternative solutions.

## Key Concepts

| Concept | Description |
|---------|-------------|
| **Checkpoint** | Snapshot of conversation state including messages, files, and context |
| **Rewind** | Return to a previous checkpoint, discarding subsequent changes |
| **Branch Point** | Checkpoint from which multiple approaches are explored |

## Accessing Checkpoints

You can access and manage checkpoints in two primary ways:

### Using Keyboard Shortcut
Press `Esc` twice (`Esc` + `Esc`) to open the checkpoint interface and browse saved checkpoints.

### Using Slash Command
Use the `/rewind` command for quick access:

```bash
# Open rewind interface
/rewind
```

## Rewind Options

When you rewind, you can choose what to restore:

- **Conversation only** - Restore chat history and context, keep current code
- **Code only** - Restore file changes, keep current conversation
- **Both** - Restore both conversation and code to the checkpoint state

## Automatic Checkpoints

Claude Code automatically creates checkpoints for you:

- **Every user prompt** - A new checkpoint is created with each user input
- **Persistent** - Checkpoints persist across sessions
- **Auto-cleaned** - Checkpoints are automatically cleaned up after 30 days (configurable)

This means you can always rewind to any previous point in your conversation, from a few minutes ago to days before.

## Use Cases

| Scenario | Workflow |
|----------|----------|
| **Exploring Approaches** | Save → Try A → Save → Rewind → Try B → Compare |
| **Safe Refactoring** | Save → Refactor → Test → If fail: Rewind |
| **A/B Testing** | Save → Design A → Save → Rewind → Design B → Compare |
| **Mistake Recovery** | Notice issue → Rewind to last good state |

## Using Checkpoints

### Viewing and Rewinding

Press `Esc` twice or use `/rewind` to open the checkpoint browser. You'll see a list of all available checkpoints with timestamps. Select any checkpoint to rewind to that state.

### Checkpoint Details

Each checkpoint shows:
- Timestamp of when it was created
- Files that were modified
- Number of messages in the conversation
- Tools that were used

## Practical Examples

### Example 1: Exploring Different Approaches

```
User: Let's add a caching layer to the API

Claude: I'll add Redis caching to your API endpoints...
[Makes changes at checkpoint A]

User: Actually, let's try in-memory caching instead

Claude: I'll rewind to explore a different approach...
[User presses Esc+Esc and rewinds to checkpoint A]
[Implements in-memory caching at checkpoint B]

User: Now I can compare both approaches
```

### Example 2: Recovering from Mistakes

```
User: Refactor the authentication module to use JWT

Claude: I'll refactor the authentication module...
[Makes extensive changes]

User: Wait, that broke the OAuth integration. Let's go back.

Claude: I'll help you rewind to before the refactoring...
[User presses Esc+Esc and selects the checkpoint before the refactor]

User: Let's try a more conservative approach this time
```

### Example 3: Safe Experimentation

```
User: Let's try rewriting this in a functional style
[Creates checkpoint before experiment]

Claude: [Makes experimental changes]

User: The tests are failing. Let's rewind.
[User presses Esc+Esc and rewinds to the checkpoint]

Claude: I've rewound the changes. Let's try a different approach.
```

### Example 4: Branching Approaches

```
User: I want to compare two database designs
[Takes note of checkpoint - call it "Start"]

Claude: I'll create the first design...
[Implements Schema A]

User: Now let me go back and try the second approach
[User presses Esc+Esc and rewinds to "Start"]

Claude: Now I'll implement Schema B...
[Implements Schema B]

User: Great! Now I have both schemas to choose from
```

## Checkpoint Retention

Claude Code automatically manages your checkpoints:

- Checkpoints are created automatically with every user prompt
- Old checkpoints are retained for up to 30 days
- You can configure the retention period in your settings
- Checkpoints are cleaned up automatically to prevent unlimited storage growth

## Workflow Patterns

### Branching Strategy for Exploration

When exploring multiple approaches:

```
1. Start with initial implementation → Checkpoint A
2. Try Approach 1 → Checkpoint B
3. Rewind to Checkpoint A
4. Try Approach 2 → Checkpoint C
5. Compare results from B and C
6. Choose best approach and continue
```

### Safe Refactoring Pattern

When making significant changes:

```
1. Current state → Checkpoint (auto)
2. Start refactoring
3. Run tests
4. If tests pass → Continue working
5. If tests fail → Rewind and try different approach
```

## Best Practices

Since checkpoints are created automatically, you can focus on your work without worrying about manually saving state. However, keep these practices in mind:

### Using Checkpoints Effectively

✅ **Do:**
- Review available checkpoints before rewinding
- Use rewind when you want to explore different directions
- Keep checkpoints to compare different approaches
- Understand what each rewind option does (conversation, code, or both)

❌ **Don't:**
- Rely on checkpoints alone for code preservation
- Expect checkpoints to track external file system changes
- Use checkpoints as a substitute for git commits

## Configuration

Configure checkpoint behavior in settings. Here's the comprehensive configuration with all available options:

```json
{
  "checkpoints": {
    "autoCheckpoint": true,
    "autoCheckpointInterval": 30,
    "maxCheckpoints": 20,
    "compressionEnabled": true,
    "includeFileContents": true
  }
}
```

### Configuration Options

- `autoCheckpoint`: Enable automatic checkpoints (default: true)
- `autoCheckpointInterval`: Minutes between auto-checkpoints (default: 30)
- `maxCheckpoints`: Maximum number of checkpoints to retain (default: 20)
- `compressionEnabled`: Compress checkpoint data to save space (default: true)
- `includeFileContents`: Include full file contents in checkpoints (default: true)

## Limitations

Checkpoints have the following limitations:

- **Bash command changes NOT tracked** - Operations like `rm`, `mv`, `cp` on the filesystem are not captured in checkpoints
- **External changes NOT tracked** - Changes made outside Claude Code (in your editor, terminal, etc.) are not captured
- **Not a replacement for version control** - Use git for permanent, auditable changes to your codebase

## Troubleshooting

### Checkpoint Too Large

**Problem**: Checkpoint creation is slow or fails

**Solution**:
```json
{
  "checkpoints": {
    "includeFileContents": false,
    "compressionEnabled": true
  }
}
```

### Missing Checkpoints

**Problem**: Expected checkpoint not found

**Solution**:
- Check if checkpoints were cleared
- Verify checkpoint retention settings
- Check disk space

### Rewind Failed

**Problem**: Cannot rewind to checkpoint

**Solution**:
- Ensure no uncommitted changes conflict
- Check if checkpoint is corrupted
- Try rewinding to a different checkpoint

## Integration with Git

Checkpoints complement (but don't replace) git:

| Feature | Git | Checkpoints |
|---------|-----|-------------|
| Scope | File system | Conversation + files |
| Persistence | Permanent | Session-based |
| Granularity | Commits | Any point |
| Speed | Slower | Instant |
| Sharing | Yes | Limited |

Use both together:
1. Use checkpoints for rapid experimentation
2. Use git commits for finalized changes
3. Create checkpoint before git operations
4. Commit successful checkpoint states to git

## Quick Start Guide

### Basic Workflow

1. **Work normally** - Claude Code creates checkpoints automatically
2. **Want to go back?** - Press `Esc` twice or use `/rewind`
3. **Choose checkpoint** - Select from the list to rewind
4. **Select what to restore** - Choose conversation, code, or both
5. **Continue working** - You're back at that point

### Keyboard Shortcuts

- **`Esc` + `Esc`** - Open checkpoint browser
- **`/rewind`** - Alternative way to access checkpoints

## Related Concepts

- **[Advanced Features](../09-advanced-features/)** - Planning mode and other advanced capabilities
- **[Memory Management](../02-memory/)** - Managing conversation history and context
- **[Slash Commands](../01-slash-commands/)** - User-invoked shortcuts
- **[Hooks](../06-hooks/)** - Event-driven automation
- **[Plugins](../07-plugins/)** - Bundled extension packages

## Additional Resources

- [Official Checkpointing Documentation](https://code.claude.com/docs/en/checkpointing)
- [Advanced Features Guide](../09-advanced-features/) - Extended thinking and other capabilities

## Summary

Checkpoints are an automatic feature in Claude Code that lets you safely explore different approaches without fear of losing work. Every user prompt creates a new checkpoint automatically, so you can rewind to any previous point in your session.

Key benefits:
- Experiment fearlessly with multiple approaches
- Quickly recover from mistakes
- Compare different solutions side-by-side
- Integrate safely with version control systems

Remember: checkpoints are not a replacement for git. Use checkpoints for rapid experimentation and git for permanent code changes.