Architecture Overview
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 enables developers to capture the entire state of a workspace—including untracked files—before performing risky operations like large-scale refactors, dependency updates, or AI agent runs.
The system is built as a Cargo workspace consisting of a core library, a CLI binary, an MCP (Model Context Protocol) server, Node.js N-API bindings, and a Claude Code plugin. It achieves high performance through XXH3-128 hashing for deduplication, LZ4 compression for storage, and a SQLite-backed catalog for incremental change detection.
Sources: CLAUDE.md:5-9, README.md:5-13
Core System Components
The project is organized into several distinct crates that separate the storage logic from the user-facing interfaces.
| Component | Description |
|---|---|
| chkpt-core | The foundational library containing the scanner, storage logic (blobs, trees, packs), SQLite index, and high-level operations. |
| chkpt-cli | A command-line interface providing commands like save, list, restore, and delete. |
| chkpt-mcp | A Model Context Protocol server using stdio transport for integration with AI tools. |
| chkpt-napi | Native Node.js bindings allowing JavaScript/TypeScript environments to invoke core functionality. |
| chkpt-plugin | A Claude Code specific plugin that provides MCP tools and automation skills. |
Sources: CLAUDE.md:13-19, README.md:104-111
Storage Architecture
The storage system is content-addressed, meaning data is identified by its hash rather than its path. This allows for efficient deduplication across different snapshots.
Store Layout
Data is stored by default in ~/.chkpt/stores/<project_id>/. The <project_id> is a deterministic 16-character hex string generated by hashing the canonical workspace path using XXH3-128.
The storage layout includes:
- catalog.sqlite: The authoritative database for snapshot metadata, manifests, and blob locations.
- index.bin: A local metadata cache used for fast incremental change detection in the current workspace.
- packs/: Files containing multiple LZ4-compressed blobs to reduce filesystem overhead.
- trees/: Content-addressed tree nodes representing the directory hierarchy.
- locks/: Contains
project.lockto prevent concurrent modifications.
Sources: crates/chkpt-core/src/config.rs:16-72, crates/chkpt-cli/skills/chkpt/references/store-layout.md:3-13
Data Schema (catalog.sqlite)
The SQLite catalog manages the relationships between snapshots and physical storage.
| Table | Primary Fields | Purpose |
|---|---|---|
| snapshots | id, root_tree_hash, parent_snapshot_id, total_files | Stores metadata and pointers to the root tree of each checkpoint. |
| snapshot_files | snapshot_id, path, blob_hash, size, mode | Flattened manifest of all files included in a specific snapshot. |
| blob_index | blob_hash, pack_hash, size | Maps content hashes to specific pack files in the packs/ directory. |
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:37-60
Save Pipeline Logic
The save operation is a multi-phase pipeline designed for speed and resource efficiency. It uses a bounded producer/consumer pipeline to stream data.
1. Workspace Scanning
The scanner walks the filesystem, respecting .chkptignore rules. It identifies file metadata such as size, mtime, and inode.
2. Incremental Detection
The system compares scanned metadata against index.bin. Files with matching mtime, size, and inode are skipped (cached), while changed or new files are marked for processing.
3. Parallel Processing
New files undergo a parallelized process:
- Hashing: XXH3-128 is used for fast content hashing.
- Compression: LZ4 compression is applied to the content.
- Deduplication: A sharded seen-hash set prevents redundant compression of identical content within the same operation.
4. Tree Building
The system builds a directory tree bottom-up. Each directory becomes a content-addressed "tree node" containing the names and hashes of its children (files and sub-directories).
Sources: crates/chkpt-core/src/ops/save.rs:77-210, crates/chkpt-core/benches/save_pipeline.rs:114-315
Security and Concurrency
To ensure data integrity, chkpt implements several safety mechanisms:
- Project Locking: A file lock (
project.lock) is acquired before any mutation (save, restore, delete) to prevent data corruption from concurrent processes. - Atomic Restore: Restores are planned before execution. The system supports a
--dry-runmode to preview changes before they are applied. - Integrity Markers: On macOS, the store includes a
.metadata_never_indexmarker to prevent Spotlight from indexing and potentially locking files during bulk writes.
Sources: crates/chkpt-core/src/config.rs:88-96, crates/chkpt-core/src/ops/save.rs:87-89, crates/chkpt-core/examples/bench_ops.rs:124-140
Conclusion
chkpt's architecture prioritizes performance and reliability by combining a content-addressed storage model with modern hashing and compression algorithms. Its use of a SQLite catalog enables fast metadata queries and efficient incremental updates, making it a robust solution for temporary workspace state management.