Frequently Asked Questions
Relevant source files
The following files were used as context for generating this wiki page:
This page provides answers to common technical and operational questions regarding the chkpt system. chkpt is a content-addressable checkpoint engine designed to save and restore workspace snapshots without relying on version control systems like Git.
It targets developers and AI agents who need high-frequency "save points" during risky operations, such as large refactors or dependency updates, providing near-instant rollbacks and incremental storage.
Sources: README.md:3-8, CLAUDE.md:5-7
General Project Overview
What is the primary purpose of chkpt?
chkpt is designed for quick, local workspace snapshots. It acts as a "save game" for your development environment, allowing you to roll back to a known-good state after a failed refactor, risky dependency change, or experimental AI agent run. It captures everything, including untracked files, which standard git stash might miss.
Sources: README.md:103-107
Does chkpt replace Git?
No. chkpt is intended for local, short-term snapshots rather than long-term version control or collaboration. Users should continue to use Git for history and collaboration, while using chkpt for immediate, low-overhead rollback points.
Sources: README.md:104-107
Storage and Performance
How is storage optimized for multiple checkpoints?
chkpt uses several techniques to minimize disk footprint:
- XXH3-128 Hashing: Content is deduplicated at the file level. Identical files across different snapshots are stored only once.
- LZ4/Zstd Compression: Every blob is compressed before storage.
- Incremental Saves: A SQLite index detects only changed files since the last save, avoiding redundant processing.
Sources: README.md:12-19, CLAUDE.md:5-7, crates/chkpt-plugin/README.md:33-35
Where are the checkpoints stored?
By default, snapshots are stored in the user's home directory at ~/.chkpt/stores/<project_id>/. This can be overridden by setting the CHKPT_HOME environment variable.
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:3-5, crates/chkpt-core/src/config.rs:18-24
How does the system handle high-volume file projects?
The system utilizes a specialized internal layout to handle metadata efficiently.
| Component | Purpose |
|---|---|
catalog.sqlite | Central database for snapshot metadata, manifests, and blob locations. |
index.bin | Binary cache for current workspace metadata to speed up change detection. |
packs/ | Directory containing packed, compressed content blobs. |
trees/ | Content-addressed tree nodes representing the directory structure. |
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:7-16
The following diagram illustrates the data flow during a save operation:
This flow ensures that only unique, compressed content enters the permanent store.
Sources: README.md:84-90, crates/chkpt-cli/skills/chkpt/references/store-layout.md:7-16
Usage and Operations
When should I proactively save a checkpoint?
It is recommended to save a checkpoint before "risky" operations:
- Refactoring: Changing more than 5 files or renaming modules.
- Deletions: Bulk removal of files or directories.
- Dependencies: Modifying files like
package.json,Cargo.toml, orrequirements.txt. - Git Operations: Before rebasing or merging where conflicts are expected.
Sources: crates/chkpt-cli/skills/chkpt/references/automation-patterns.md:5-13
How can I verify a restore before applying it?
Use the --dry-run flag with the restore command. This provides a preview of added, changed, and removed files without actually modifying the workspace.
Sources: crates/chkpt-cli/skills/chkpt/references/cli-commands.md:46-55
How does chkpt identify different projects?
chkpt generates a deterministic 16-character hex string as a project_id based on the canonical path of the workspace. This ensures that the same workspace always maps to the same store directory.
Sources: crates/chkpt-core/src/config.rs:4-9, crates/chkpt-napi/test/config.spec.ts:15-18
Internal Architecture
What is the catalog schema?
The catalog.sqlite file contains several key tables for managing state:
| Table | Key Fields | Description |
|---|---|---|
snapshots | id, message, root_tree_hash | High-level metadata for each checkpoint. |
snapshot_files | path, blob_hash, size | The flattened manifest of every file in a specific snapshot. |
blob_index | blob_hash, pack_hash | Mapping of content hashes to their physical storage location in pack files. |
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:32-55
How are tree nodes structured?
Directory structures are represented as content-addressed tree nodes. Each TreeEntry contains the name, entry type (file/dir), hash, size, and file mode. These are stored on disk under trees/<prefix>/<rest_of_hash>.
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:81-91, crates/chkpt-core/src/config.rs:60-64
The diagram shows the hierarchical relationship between snapshots, directory trees, and the underlying content blobs.
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:32-91
Troubleshooting
What should I do if I encounter a "Lock held" error?
This occurs when another chkpt process (e.g., an MCP server and a CLI instance) is accessing the same project store simultaneously. You should wait for the other operation to complete or check for hung processes.
Sources: crates/chkpt-cli/skills/chkpt/SKILL.md:65-66, crates/chkpt-cli/skills/chkpt/references/cli-commands.md:82
How do I recover if the catalog is corrupted?
While direct modification is discouraged, the store layout is designed for inspection. You can use standard SQLite tools to query the catalog or inspect the packs/ and trees/ directories to verify content integrity.
Sources: crates/chkpt-cli/skills/chkpt/references/store-layout.md:57-80