chkpt

chkpt

Save and restore your entire workspace without touching Git.

chkpt is a fast, content-addressable checkpoint system. One chkpt save before a big refactor, dependency update, or AI agent run, and you can roll back anytime. Unlike git stash or temporary branches, chkpt captures everything (including untracked files), deduplicates content with XXH3-128 hashing, and compresses with LZ4. Snapshots are fast and take up little disk space.

Features

• Content-addressed deduplication via XXH3-128 hashing. Identical files are stored only once.
• LZ4 compression for every blob, keeping storage small.
• Incremental saves with a SQLite index that detects only changed files.
• Catalog-backed metadata for fast snapshot lookup, listing, and restore planning.
• Atomic restore that keeps your workspace intact if something fails midway.
• Optional dependency scanning when you want to include node_modules, .venv, and similar directories.
• Multiple interfaces: CLI, Node.js API, MCP server, and Claude Code plugin.

Performance

Benchmarked on MacBook Pro (Apple M2 Pro, 16 GB RAM, APFS SSD). Release build, median of 3 runs.

Project	Files	Size	Cold Save	Incr. Save	Restore	Storage	Ratio	Incr. Storage (new data)
React	6,879	34.4 MB	0.26s	0.05s	0.03s	19.5 MB	1.7x	+2.5 MB (7.4 KB)
Rust	58,760	195.9 MB	2.04s	0.33s	0.18s	96.0 MB	2.0x	+15.8 MB (2.2 KB)
Linux kernel	92,923	1.4 GB	2.95s	0.47s	0.24s	503.3 MB	2.9x	+22.9 MB (25 KB)

Cold Save = first checkpoint with empty store. Incr. Save = re-save after modifying 5 files. Storage = total .chkpt store size after cold save (LZ4-compressed, content-deduplicated). Ratio = original size / storage size. Incr. Storage = total store growth per incremental save (includes metadata). Parenthesized value = actual new file content stored.

Getting Started

Requirements

• CLI (Rust): Rust toolchain (for cargo install)
• CLI / MCP (Node.js): Node.js 18 or later (for npx)

Install

CLI via Cargo

cargo install chkpt-cli

CLI via npx

npx chkpt

MCP Server

npx @chkpt/mcp

Claude Code Plugin (recommended)

# Add the marketplace
/plugin marketplace add syi0808/chkpt

# Install the plugin
/plugin install chkpt@chkpt-marketplace

This activates 4 MCP tools and the automation skill (/chkpt:chkpt).

Usage

CLI

# Save current workspace
chkpt save -m "before refactor"

# List checkpoints
chkpt list

# Restore to latest checkpoint
chkpt restore latest

# Preview restore without applying
chkpt restore <id> --dry-run

# Delete a checkpoint
chkpt delete <id>

Optional Dependency Inclusion

# Include dependency directories (node_modules, .venv, etc.)
chkpt save --include-deps

Claude Code MCP Tools

Tool	Description
checkpoint_save	Save a workspace snapshot
checkpoint_list	List available checkpoints
checkpoint_restore	Restore to a checkpoint (dry-run supported)
checkpoint_delete	Delete a checkpoint

Automation Skill (/chkpt:chkpt)

Invoke /chkpt:chkpt in Claude Code to:

• Get automatic checkpoint suggestions before risky operations (large refactors, file deletion, dependency changes)
• Save, restore, and delete checkpoints conversationally
• Compare differences between snapshots

How It Works

Workspace                      ~/.chkpt/stores/
┌──────────────┐              ┌──────────────────┐
│  src/        │   save →     │  trees/           │
│  tests/      │              │  packs/           │
│  Cargo.toml  │   ← restore │  catalog.sqlite   │
└──────────────┘              │  index.bin        │
                              └──────────────────┘

1. Scan: walk files according to .chkptignore rules
2. Hash: generate an XXH3-128 content hash for each file
3. Deduplicate: skip content already in the store
4. Compress & store: write new content with LZ4 compression
5. Record snapshot: persist metadata and manifest in catalog.sqlite

Project Structure

crates/
├── chkpt-core/      # Core library (scanner, store, index, ops)
├── chkpt-cli/       # CLI binary
├── chkpt-mcp/       # MCP stdio server
├── chkpt-napi/      # Node.js native bindings (NAPI)
├── chkpt-mcp-npm/   # @chkpt/mcp npm package
└── chkpt-plugin/    # Claude Code plugin

FAQ