checkpointing

name	checkpointing
description	How checkpointing works for tracking file changes and rewinding to previous states. Use when user asks about checkpoints, rewinding, rollback, undo, or restoring previous states.

Claude Code Checkpointing

Overview

Claude Code includes an automatic checkpointing system that tracks file edits and allows users to recover from unwanted changes during development sessions.

How Checkpointing Works

Automatic Tracking

The system captures code states before each modification.

Key features:

• Every user prompt creates a new checkpoint
• Checkpoints persist across resumed conversations
• Automatic cleanup occurs after 30 days (configurable)

What Gets Tracked

Tracked:

• Direct file edits via Edit tool
• File creations via Write tool
• File modifications by Claude

Not tracked:

• Files modified by bash commands (rm, mv, cp)
• Manual file modifications outside Claude Code
• Changes from concurrent sessions (unless they affect files the current session modified)

Rewinding Changes

Access Rewind Menu

Keyboard shortcut: Press Esc twice (quickly)

Slash command:

/rewind

Restoration Options

When you open the rewind menu, you have three options:

1. Conversation Only

Keeps: All code changes Reverts: Conversation history to selected checkpoint

Use when:

• You want to start conversation over
• Code changes are good
• You want to try different approach in conversation

2. Code Only

Keeps: Conversation history Reverts: Files to selected checkpoint

Use when:

• Recent changes broke something
• Want to undo code changes
• Conversation context is valuable

3. Both Code and Conversation

Reverts: Everything to selected checkpoint (full rollback)

Use when:

• Complete do-over needed
• Both code and conversation went wrong
• Want to return to known good state

Selecting a Checkpoint

Checkpoints are displayed with:

• Timestamp
• User prompt that created it
• Files affected
• Changes summary

Navigate with arrow keys and select with Enter.

Use Cases

Testing Different Approaches

Scenario: Try multiple implementation strategies without losing starting point.

# Approach 1
"implement feature using strategy A"
# Review, not ideal

# Rewind
Esc Esc → Select checkpoint → Code only

# Approach 2
"implement feature using strategy B"
# Better!

Quick Bug Recovery

Scenario: Recent changes introduced a bug.

# Make changes
"refactor the authentication module"
# Oops, broke login

# Rewind
Esc Esc → Select checkpoint before refactor → Code only

# Try again differently
"refactor authentication but keep existing login flow"

Iterative Development

Scenario: Preserve working states while iterating.

# Working state 1
"add basic user validation"
# Works ✓

# Iterate
"add more complex validation rules"
# Issues found

# Return to working state
Esc Esc → Code only

# Try different iteration
"add regex-based validation"

Conversation Reset

Scenario: Conversation got confused or went off track.

# Good code changes made
"add user profile endpoint"
"add user settings endpoint"

# Conversation gets confusing
# Want to restart conversation but keep code

# Rewind conversation only
Esc Esc → Conversation only → Select early checkpoint

# Fresh conversation start with code intact

Important Limitations

Bash Command Changes Not Tracked

Not captured:

!rm file.txt
!mv old.txt new.txt
!cp source.txt dest.txt
!git checkout -b new-branch

Why: Bash commands run outside Claude's file tracking system.

Workaround:

• Use Claude's Edit/Write tools instead when possible
• Manually track bash file operations
• Use git for version control of important changes

External Changes Not Tracked

Not captured:

• Manual edits in your text editor
• IDE refactorings
• File system operations outside Claude Code
• Changes from other tools

Workaround:

• Use git to track all changes
• Create manual checkpoints with git commits
• Be aware of what Claude modified vs what you modified

Concurrent Session Caveats

Limited tracking: If multiple Claude Code sessions modify the same files, only changes from the current session are tracked for checkpointing.

Best practice: Use one Claude Code session at a time per project.

Not a Version Control Replacement

Checkpointing vs Git

Feature	Checkpointing	Git
Scope	Session-level	Repository-wide
Duration	30 days	Permanent
Granularity	Per prompt	Per commit
Collaboration	Single user	Team
Purpose	Session recovery	Version control
Bash tracking	No	Yes

Use Both Together

Git for:

• Permanent history
• Collaboration
• Branch management
• All file changes (including bash)
• Release management

Checkpointing for:

• Quick session rollback
• Trying different approaches
• Recovering from mistakes
• Conversation management
• Rapid iteration

Recommended workflow:

# Regular git commits for milestones
git commit -m "Working authentication"

# Use checkpointing for rapid iteration
"try optimization A"
Esc Esc → rewind if not good
"try optimization B"
Esc Esc → rewind if not good
"try optimization C"
# This one works!

# Commit the winner
git add .
git commit -m "Optimized authentication"

Configuration

Checkpoint Retention

Default: 30 days

Configure retention: Edit .claude/settings.json:

{
  "checkpointRetentionDays": 60
}

Disable Checkpointing

Not recommended, but possible:

{
  "enableCheckpointing": false
}

Best Practices

1. Review Before Rewinding

Look at:

• What checkpoint contains
• What will be lost
• What will be kept

Avoid:

• Blindly selecting checkpoints
• Rewinding without understanding impact

2. Use Descriptive Prompts

Good (easy to identify):

"add email validation to user registration"
"refactor database queries for performance"

Bad (hard to identify):

"make changes"
"fix it"

Checkpoints show your prompts, so descriptive prompts make checkpoint selection easier.

3. Combine with Git

# Checkpoint for rapid iteration
Try approach → rewind → try approach → rewind

# Git for confirmed changes
git add .
git commit -m "Final implementation"

4. Rewind Code, Not Conversation

Often better: Rewind code only and keep conversation history.

Why:

• Maintains context
• Claude learns from mistakes
• Can explain what went wrong
• Better for iterative improvement

5. Regular Git Commits

Don't rely solely on checkpoints:

# After significant progress
git add .
git commit -m "Checkpoint: working user authentication"

# Continue with Claude Code
# Checkpointing handles rapid iteration
# Git handles permanent milestones

Troubleshooting

Checkpoint Not Showing Expected State

Possible causes:

• Changes made via bash commands (not tracked)
• External file modifications
• Concurrent session changes
• Checkpoint expired (>30 days)

Solution:

• Use git for those scenarios
• Check git history: git log
• Review git diff: git diff

Can't Find Recent Checkpoint

Check:

• Are you in the right directory?
• Is this the same session?
• Did checkpoint expire?

Solution:

• Use /rewind command instead of Esc Esc
• Check session history
• Verify working directory

Rewind Not Working

Check:

• Are files write-protected?
• Do you have filesystem permissions?
• Are files open in another program?

Solution:

• Close files in editors
• Check file permissions
• Ensure no file locks

Example Workflows

Refactoring Safely

# Current working state
git commit -m "Pre-refactor checkpoint"

# Try refactoring
"refactor user controller for better error handling"

# Test
!npm test

# If tests fail
Esc Esc → Code only → Return to pre-refactor

# Try different approach
"refactor user controller with focus on backward compatibility"

# If tests pass
git commit -m "Refactored user controller"

Feature Experimentation

# Baseline working
git commit -m "Baseline"

# Experiment 1
"add feature using approach A"
# Review, note pros/cons

# Rewind
Esc Esc → Code only

# Experiment 2
"add feature using approach B"
# Compare, choose better

# If experiment 2 is better
git commit -m "Added feature using approach B"

# If neither was good
Esc Esc → Code only → Back to baseline

Conversation Management

# Making good progress
"implement auth"
"add user roles"
"add permissions"

# Conversation gets complex/confused
Esc Esc → Conversation only → Select first checkpoint

# Start fresh conversation
"explain the architecture we just built"
# Code intact, conversation reset