Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
520
.claude/CHECKPOINTING_GUIDE.md
Normal file
520
.claude/CHECKPOINTING_GUIDE.md
Normal file
@@ -0,0 +1,520 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user