Introduction to chkpt
Relevant source files
The following files were used as context for generating this wiki page:
chkpt is a fast, content-addressable checkpoint system designed for saving and restoring workspace snapshots without involving Git. It captures the entire workspace state, including untracked files, by utilizing XXH3-128 (or BLAKE3 in some contexts) content hashing for deduplication and LZ4 or zstd compression for storage efficiency. The system is intended as a "save game" for workspaces, allowing developers to roll back to known-good states before risky operations like large refactors or dependency updates.
Sources: README.md:3-9, CLAUDE.md:7-9
The project is structured as a Cargo workspace containing a core Rust library, a CLI binary, an MCP (Model Context Protocol) server, Node.js native bindings via N-API, and a Claude Code plugin. It supports incremental saves by using a SQLite-based index to detect only modified files, ensuring that snapshots are both fast and space-efficient.
Sources: CLAUDE.md:11-18, README.md:14-18
Core Features and Performance
The chkpt system focuses on deduplication, compression, and atomicity to provide high-performance workspace management.
| Feature | Description |
|---|---|
| Deduplication | Content-addressed storage ensures identical files are stored only once using XXH3-128 or BLAKE3 hashes. |
| Compression | Utilizes LZ4 or zstd compression for blobs to minimize disk footprint. |
| Incremental Saves | Employs a SQLite index to track workspace metadata and only process changed files. |
| Atomic Restore | Ensures workspace integrity by preventing partial restores if a failure occurs. |
| Dependency Scanning | Optional inclusion of directories like node_modules or .venv. |
Sources: README.md:12-20, CLAUDE.md:7-9
System Performance
Benchmarking on real-world projects shows significant storage ratios and rapid incremental save times. For example, the Linux kernel (approx. 1.4 GB) can be incrementally saved in approximately 0.47s with a 2.9x storage compression ratio.
Sources: README.md:22-31
System Architecture
The architecture of chkpt is divided into a workspace-facing frontend and a content-addressed backend stored in the user's home directory.
High-Level Data Flow
When a user executes a save operation, the system follows a structured pipeline to move data from the workspace to the persistent store.
The diagram above illustrates the snapshot creation process: scanning files based on .chkptignore, hashing content, skipping existing blobs, and recording metadata in a SQLite catalog.
Sources: README.md:83-91, crates/chkpt-cli/skills/chkpt/references/store-layout.md:6-14
Component Layout
The project consists of several specialized crates:
- chkpt-core: The core library containing the scanner, store (blob/tree/pack), and indexing logic.
- chkpt-cli: A command-line interface using
clapanddialoguer. - chkpt-mcp: An MCP server providing tools to AI agents.
- chkpt-napi: Node.js native bindings for JavaScript integration.
- chkpt-plugin: A Claude Code plugin that integrates automation skills and MCP tools.
Sources: CLAUDE.md:11-18, README.md:93-101
Storage and Data Model
chkpt stores data in a dedicated directory, typically ~/.chkpt/stores/<project_id>/. This directory contains the metadata catalog, content-addressed trees, and compressed data packs.
Directory Structure
~/.chkpt/stores/<project_id>/
├── catalog.sqlite # Snapshot metadata, manifests, and blob locations
├── index.bin # Cache for current workspace metadata
├── locks/ # Concurrency control (project.lock)
├── trees/ # Content-addressed tree nodes
└── packs/ # Packed blobs and indexes
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:3-14
Catalog Schema (SQLite)
The catalog.sqlite file is the central authority for snapshot history and file manifests.
| Table | Purpose | Key Fields |
|---|---|---|
| snapshots | High-level snapshot metadata | id, message, root_tree_hash, total_files, total_bytes |
| snapshot_files | Flattened manifest of every file in a snapshot | snapshot_id, path, blob_hash, size, mode |
| blob_index | Physical location of data blobs | blob_hash, pack_hash, size |
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:28-56
Operational Workflow
The system provides several primary operations: save, list, restore, and delete.
Save and Restore Sequence
Restoration is a critical operation that requires safety checks, specifically a "dry-run" to preview changes before they are applied.
Automation Patterns
The chkpt system defines specific patterns for when snapshots should be suggested to users, particularly through its Claude Code plugin integration.
- Risky Operations: Snapshots are suggested before large refactors (>5 files), directory deletions, dependency changes (e.g.,
package.json), or risky Git operations (e.g.,rebase). - Milestones: Suggestions occur after major feature completion or when all tests pass.
- Recovery: If an operation fails, the system suggests restoring from the most recent checkpoint.
Sources: crates/chkpt-cli/skills/chkpt/references/automation-patterns.md:3-33
CLI Usage Reference
The CLI is the primary manual interface for interacting with the store.
| Command | Usage | Notable Options |
|---|---|---|
save | chkpt save -m "msg" | --include-deps to include node_modules. |
list | chkpt list | --limit <n>, --full for complete IDs. |
restore | chkpt restore <id> | --dry-run (REQUIRED before actual restore). |
delete | chkpt delete <id> | Triggers garbage collection. |
Sources: crates/chkpt-cli/skills/chkpt/references/cli-commands.md:5-84
Summary
chkpt provides a robust, local-first alternative to temporary Git branches or stashes by leveraging content-addressed storage and SQLite indexing. Its architecture emphasizes speed through deduplication and LZ4/zstd compression, making it suitable for rapid workspace snapshots during development. Through its various interfaces—CLI, N-API, and MCP—it serves as a foundational tool for both human developers and AI-driven workspace agents to maintain "save points" during complex workflows.
Sources: README.md:103-116, CLAUDE.md:7-18