CCCheckpoints

A powerful CLI tool for creating and tracking checkpoints in Claude Code projects. Never lose your work again with automatic checkpointing, intelligent rollbacks, and seamless integration with Claude Code's AI-powered development workflow.

✨ Features

• 🔄 Automatic Checkpointing - Creates checkpoints automatically when Claude modifies files
• 📸 Manual Snapshots - Create checkpoints manually at any time
• ⏪ Smart Rollbacks - Roll back to any checkpoint with precision
• 🔀 Prompt Revert Detection - Automatically restores files when reverting to previous prompts
• 🗂️ File-Level Control - Roll back individual files or entire project states
• 🎯 Claude Code Integration - Seamless hooks and slash commands for Claude Code workflow
• 🖥️ Interactive UI - Beautiful terminal UI for checkpoint management
• 📊 Diff Visualization - See exactly what changed between checkpoints
• 🧹 Intelligent Cleanup - Automatic pruning of old checkpoints
• ⚡ Fast & Lightweight - Minimal overhead, maximum performance

🚀 Quick Start

Installation

Install globally using npx (recommended):

npx cccheckpoints install

This will:

1. Install CCCheckpoints globally
2. Set up Claude Code integration
3. Make the ccc command available system-wide

Alternative Installation

# Install globally via npm
npm install -g cccheckpoints

# Set up Claude Code integration
ccc install

Initialize in a Project

# Navigate to your project
cd your-project

# Initialize CCCheckpoints
ccc init

# Check status
ccc status

📖 Usage

Basic Commands

# Initialize CCCheckpoints in current project
ccc init

# Check project status
ccc status

# List all checkpoints
ccc list

# Create a manual checkpoint
ccc checkpoint --prompt "Before refactoring" --session-id "manual"

# Show checkpoint details
ccc show <checkpoint-id>

# View differences
ccc diff <checkpoint-id>

# Rollback to a checkpoint
ccc rollback <checkpoint-id>

# Rollback a single file
ccc rollback-file <checkpoint-id> <file-path>

# Launch interactive UI
ccc ui

Advanced Features

# Prune old checkpoints
ccc prune --older-than 7

# Update to latest version
ccc update

# Show help for any command
ccc help [command]

# Configure settings
ccc config set maxCheckpoints 50
ccc config list

🔧 Configuration

CCCheckpoints can be configured per project or globally:

# Set maximum checkpoints to retain
ccc config set maxCheckpoints 25

# Enable/disable automatic checkpointing
ccc config set autoCheckpoint true

# Set cleanup interval (days)
ccc config set cleanupInterval 7

# List all configuration
ccc config list

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | maxCheckpoints | 10 | Maximum number of checkpoints to retain | | autoCheckpoint | true | Enable automatic checkpointing | | cleanupInterval | 7 | Days after which to clean up old checkpoints | | diffContext | 3 | Lines of context in diff output |

🤖 Claude Code Integration

CCCheckpoints integrates seamlessly with Claude Code through hooks:

Automatic Checkpointing

• Pre-Tool Hook: Creates checkpoints before Claude modifies files
• Post-Tool Hook: Tracks which files were actually modified
• Session-End Hook: Cleans up unnecessary checkpoints

Slash Commands

Use CCCheckpoints directly within Claude Code:

/ccc-list                    # List recent checkpoints
/ccc-status                  # Show project status
/ccc-diff <checkpoint-id>    # Show checkpoint changes
/ccc-rollback <checkpoint-id> # Rollback to checkpoint
/ccc-undo                    # Undo last changes

Supported Tools

• ✅ Write operations
• ✅ Edit operations
• ✅ MultiEdit operations
• ✅ File creation and deletion

🎨 VSCode Extension

Take your checkpoint management to the next level with our VSCode extension! Get visual checkpoint management directly in your editor with:

• 📊 Visual Checkpoint Tree - See all checkpoints in the Explorer sidebar
• 🖱️ One-Click Actions - Rollback, diff, and delete with simple clicks
• 📝 Context Menus - Create checkpoints from any file or editor
• ⚡ Real-Time Updates - Automatic refresh when checkpoints change
• 🔧 Customizable Settings - Configure display options and behavior

Installation

# Install during initial setup (interactive)
ccc install

# Or install only the VSCode extension
ccc install --vscode code      # For VS Code
ccc install --vscode cursor    # For Cursor
ccc install --vscode code-insiders  # For VS Code Insiders

The extension automatically activates when it detects a CCCheckpoints-enabled project (.ccc folder) and provides an intuitive interface for all checkpoint operations without leaving your editor.

🛠️ Development

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• Claude Code

Local Development

# Clone the repository
git clone https://github.com/roandegraaf/cccheckpoints.git
cd cccheckpoints

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Install locally for testing
npm install -g .

Scripts

npm run build          # Compile TypeScript
npm run dev            # Watch mode compilation
npm run test           # Run test suite
npm run test:watch     # Watch mode testing
npm run lint           # Lint code
npm run format         # Format code

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

🙏 Acknowledgments

• Built for the Claude ecosystem
• Inspired by Git's checkpoint philosophy
• Thanks to all contributors and users