Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
chkpt is a fast, content-addressable checkpoint system designed to capture and restore workspace snapshots without relying on Git. It utilizes XXH3-128 hashing for deduplication, LZ4 compression for storage efficiency, and a SQLite index for incremental saves. This system is particularly useful for protecting work during risky operations such as large refactors, dependency updates, or AI agent runs.
The project is structured as a Cargo workspace with multiple interfaces, including a CLI, a Node.js API (N-API bindings), an MCP server, and a Claude Code plugin.
Sources: README.md:1-15, CLAUDE.md:1-10
Installation and Requirements
Depending on your preferred environment, chkpt can be installed via Cargo or utilized through Node.js.
Requirements
- Rust Environment: A working Rust toolchain is required for native compilation and CLI installation via Cargo.
- Node.js Environment: Node.js 18 or later is required for using the N-API bindings or running the CLI/MCP server via
npx.
Sources: README.md:33-36, crates/chkpt-napi/package.json:34-36
Installation Methods
| Method | Command | Description |
|---|---|---|
| Cargo (CLI) | cargo install chkpt-cli | Installs the native Rust CLI binary. |
| npx (CLI) | npx chkpt | Runs the CLI directly using Node.js. |
| MCP Server | npx @chkpt/mcp | Starts the Model Context Protocol server. |
| Claude Plugin | /plugin install chkpt@chkpt-marketplace | Installs the automation skill for Claude Code. |
Sources: README.md:38-58, crates/chkpt-plugin/README.md:5-13
Core Workflow and Architecture
The chkpt system operates through a structured pipeline that ensures data integrity and storage efficiency. When a checkpoint is saved, the system scans the workspace, hashes file contents, deduplicates existing data, and persists compressed blobs.
The Save Pipeline
The following diagram illustrates the sequence of operations during a chkpt save command.
The system utilizes a SQLite catalog to track metadata and snapshot manifests, allowing for fast lookups and incremental updates.
Sources: README.md:83-93, CLAUDE.md:1-10
Store Layout
chkpt stores its data in a dedicated directory, typically located at ~/.chkpt/stores/<project_id>/. The project ID is a deterministic 16-hex-char string derived from the workspace path.
The store layout manages everything from raw data blobs (packs) to the hierarchical directory structures (trees).
Sources: crates/chkpt-core/src/config.rs:5-50, CLAUDE.md:5-15
Basic Usage
The CLI provides a straightforward set of commands for managing checkpoints.
Common Commands
-
Save a Snapshot:
chkpt save -m "message"
Captures the current state of the workspace. Use--include-depsto include directories likenode_modulesor.venv. -
List Snapshots:
chkpt list
Displays a history of available checkpoints. -
Restore Workspace:
chkpt restore <id>
Reverts the workspace to a previous state. It is highly recommended to use--dry-runfirst to preview changes. -
Delete Snapshot:
chkpt delete <id>
Removes a specific checkpoint from the store.
Sources: README.md:60-75, crates/chkpt-plugin/skills/chkpt/SKILL.md:38-46
Development Setup
For contributors looking to build or test chkpt locally, the repository is organized as a Cargo workspace.
Building from Source
To build all crates and run tests:
# Clone the repository
git clone https://github.com/syi0808/chkpt.git
cd chkpt
# Build all Rust crates
cargo build
# Run Rust tests
cargo test --workspace
Sources: CONTRIBUTING.md:30-36, CLAUDE.md:16-20
Node.js Bindings Development
The N-API bindings located in crates/chkpt-napi require specific tools for cross-compilation, such as napi-rs and cargo-xwin for Windows targets.
cd crates/chkpt-napi
pnpm install
pnpm build
pnpm test
Sources: CONTRIBUTING.md:38-43, crates/chkpt-napi/README.md:5-15
Summary
chkpt provides a high-performance alternative to traditional version control for local, short-term workspace snapshots. By combining XXH3-128 hashing, LZ4 compression, and a structured SQLite-backed storage model, it offers near-instantaneous save and restore capabilities. Developers can integrate chkpt into their workflows via the CLI for manual protection or through the Claude Code plugin for proactive automation during risky development tasks.
Sources: README.md:1-10, crates/chkpt-plugin/skills/chkpt/SKILL.md:14-25