Claude Code 2.0 Checkpoint Feature Practical Guide - Recovery Patterns and Operational Strategies¶

This is a followup to the morning article

For basic feature overview: Claude Code v2.0 Release

Target Audience: Intermediate developers familiar with Claude Code v2.0 basics

Goals¶

Use 3 checkpoint restore modes effectively in real-world scenarios
Accelerate error recovery and experimental code changes
Establish effective operational patterns with Git integration

Checkpoint Feature Basic Architecture¶

Auto-save Triggers¶

Checkpoints are automatically created per user prompt submission. The following are NOT captured:

Claude's standalone code changes
Direct user edits in editor
Changes via bash commands

Retention and Storage¶

30-day automatic retention
Saved in local .claude/checkpoints/ directory
Managed independently per project

Access Methods¶

Operation	Command
List checkpoints	`/checkpoints`
Launch restore UI	Press `Esc` twice or `/rewind`
Restore specific point	`/rewind <checkpoint_id>`

3 Restore Modes and Real-world Scenarios¶

Mode 1: Conversation Only Restore (Recommended frequency: High)¶

Use Cases: - Reject Claude's proposal and request alternative approach - Retry with different prompt wording - Reset conversation when context becomes bloated

Example Execution: - Situation: Claude proposed large-scale refactoring across 10 files - Decision: Impact scope too large - Operation: /rewind → Select "conversation only" → Re-instruct "Refactor only auth.ts first" - Result: File changes preserved, conversation redone

Best Practices: - Pivot strategy while preserving code changes - Token savings (remove unnecessary conversation history) - Protect manually edited sections

Mode 2: Code Only Restore (Recommended frequency: Medium)¶

Use Cases: - Claude's generated code has critical bugs - Implementation differs from expectations but want to keep conversation context - Try multiple implementation approaches (A/B testing)

Example Execution: - Situation: After adding API endpoint, all existing tests fail - Decision: New endpoint is fine but existing code modification inappropriate - Operation: /rewind → Select "code only" → Add instruction "Don't modify existing endpoints" - Result: Code rolled back, re-implementation with conversation context

Best Practices: - Maintain conversation flow - Redo only code while keeping Claude's understanding - Use conversation history as failure pattern record

Mode 3: Both Restore (Recommended frequency: Low)¶

Use Cases: - Completely change direction - All changes across multiple prompts become unnecessary - Reset experimental large-scale changes

Example Execution: - Situation: Progressed GraphQL migration over 5 prompts, but requirement changed to continue REST API - Decision: Wipe entire work - Operation: /checkpoints → Identify ID → /rewind <id> → Select "both" - Result: Code and conversation completely returned to pre-migration state

Caution: - Direct user edits are NOT restored (Git management recommended) - Full restore after long sessions risks token waste

Failure Patterns and Countermeasures¶

Symptom	Cause	Countermeasure
Issue persists after restore	User's direct edits are the cause	Check Git diff → Manual fix
Cannot restore past 30 days	Retention expired	Create Git branch for important experiments
Checkpoint bloat	Excessive fragmentation	Delete unnecessary history with `/clear`
Context loss after restore	Deleted too much conversation	Prioritize Mode 1 usage

Git Integration Operational Strategy¶

Recommended Workflow¶

graph LR
    A[Start new feature] --> B[Create Git branch]
    B --> C[Request implementation to Claude]
    C --> D{Review result}
    D -->|OK| E[Git commit]
    D -->|NG| F[Checkpoint restore]
    F --> C
    E --> G{Further improvement?}
    G -->|Yes| C
    G -->|No| H[Create PR]

Decision Criteria¶

Operation	Claude Checkpoint	Git
Short-term experiment recovery	✅ Recommended	❌ Pollutes commits
Long-term storage	❌ 30-day limit	✅ Permanent storage
Team sharing	❌ Local only	✅ Can push
Conversation context preservation	✅ Possible	❌ Not possible

Practical Example: Experimental Refactoring¶

# 1. Build safety net
git checkout -b experiment/refactor-auth

# 2. Request Claude
# "Rewrite auth.ts in functional style"

# 3. Test results
npm test

# 4a. Success pattern
git add auth.ts
git commit -m "refactor: convert auth.ts to functional style"

# 4b. Failure pattern
# Esc×2 → Code only restore → Re-instruct
# Or
git reset --hard  # Complete reset via Git

Automation & Extension Patterns¶

Periodic Checkpoint Cleanup¶

Script example to delete checkpoints older than 15 days:

find .claude/checkpoints -type f -mtime +15 -delete

CI/CD Integration (NOT Recommended)¶

Checkpoints are for local development only. Trust only Git in CI environments.

Team Convention Example¶

Usage Timing: Trying multiple approaches during 1 feature implementation → Checkpoint / Saving after feature completion → Git commit
Prohibited Actions: Git management of checkpoint directory, Expecting restore after 30-day expiration

Benchmark: Restore Speed¶

Operation	Time Required	Notes
Checkpoint creation	< 0.1s	No user perception
Conversation only restore	< 0.5s	Instant
Code only restore	1-3s	Depends on file count
Both restore	1-5s	Depends on project scale
Git reset --hard	0.5-2s	Reference comparison

Conclusion: Checkpoints match or exceed Git speed, with conversation preservation advantage.

Next Steps¶

Claude Code v2.0 Release - Full picture overview
Claude Code Complete Guide - From basics to advanced
CLAUDE.md Practical Guide - Project configuration optimization

Important Notes: - Checkpoints are session management tools, NOT a replacement for permanent version control - Always manage important code changes with Git - Information in this article is based on Claude Code v2.0.0 (released September 30, 2025)

Official Documentation: https://docs.claude.com/en/docs/claude-code/overview