claude-code-checkpoint/README.md

Automatic project snapshots for Claude Code - never lose your work again

# 🚀 Claude Code Checkpoint

[![npm version](https://badge.fury.io/js/claude-code-checkpoint.svg)](https://www.npmjs.com/package/claude-code-checkpoint)

> Automatic project snapshots for Claude Code - never lose your work again!

## What is this?

Claude Code Checkpoint automatically creates snapshots of your project after every Claude operation. Think of it as "auto-save" for your entire codebase - capturing the state after each AI-assisted change.

## Features

- 📸 **Automatic Snapshots** - Creates checkpoints after every Claude operation
- 🔍 **Smart Change Detection** - Only saves when files actually change
- ↩️ **Easy Restore** - Restore to any previous checkpoint with one command
- 📊 **Checkpoint History** - View and manage all your checkpoints
- 🚫 **Smart Exclusions** - Ignores node_modules, .git, build files, etc.
- 💾 **Efficient Storage** - Uses rsync for fast, space-efficient snapshots

## Installation

```bash
npx claude-code-checkpoint
```

This single command will:
1. Install the checkpoint hook into Claude Code
2. Set up the `checkpoint` command in your PATH
3. Configure automatic snapshots on file changes
4. Create your first checkpoint

## Usage

### Automatic Checkpoints

Once installed, checkpoints are created automatically after every Claude operation that modifies files. You don't need to do anything!

### Manual Commands

```bash
# List all checkpoints
checkpoint list

# Restore to a specific checkpoint
checkpoint restore 5
checkpoint restore last
checkpoint restore previous

# Create a manual checkpoint
checkpoint create "Before major refactor"

# Compare checkpoints
checkpoint diff 3 5

# View checkpoint details
checkpoint show 5

# Clear all checkpoints for current project
checkpoint clear
```

## How It Works

1. **Hook Integration** - Integrates with Claude Code's STOP hook
2. **Change Detection** - Uses SHA256 hashing to detect file changes
3. **Smart Storage** - Creates full snapshots only when changes occur
4. **Project Isolation** - Each git repository has its own checkpoint history

## Storage Location

Checkpoints are stored in:
```
~/.claude/checkpoint/data/YOUR_PROJECT_NAME/
```

## Exclusions

The following are automatically excluded from checkpoints:
- `.git/` - Version control
- `node_modules/` - Dependencies
- `dist/`, `build/`, `.next/` - Build outputs
- `__pycache__/`, `*.pyc` - Python cache
- `.DS_Store` - System files
- And more...

## Examples

### Scenario 1: Oops, Claude broke something!
```bash
# See what checkpoints are available
checkpoint list

# Output:
# 1. Initial state (30 minutes ago)
# 2. Added authentication (25 minutes ago)
# 3. Updated database schema (10 minutes ago)
# 4. Refactored user model (5 minutes ago) ← This broke things!

# Restore to before the breaking change
checkpoint restore 3
```

### Scenario 2: Compare changes
```bash
# See what changed between checkpoints
checkpoint diff 2 4

# Output shows all file modifications
```

## Uninstall

To remove the checkpoint system:
```bash
npx claude-code-checkpoint uninstall
```

## Requirements

- Claude Code CLI installed
- Git repository (checkpoints work per-project)
- macOS, Linux, or Windows with WSL

## Author

Created by mrrxwyz

## License

MIT License - see LICENSE file for details.