Storage Directory Layout
Relevant source files
The following files were used as context for generating this wiki page:
The storage directory layout in chkpt is designed to support a fast, content-addressable checkpoint system. It separates project-specific metadata from shared content blobs, using deduplication via XXH3-128 hashing and LZ4 compression to minimize disk usage. All persistence for a given workspace is managed under a unique project ID derived from the workspace path.
Sources: CLAUDE.md:7-9, crates/chkpt-core/src/config.rs:4-8
Global and Project Root
By default, chkpt stores all data within a .chkpt directory located in the user's home directory. This base location can be overridden using the CHKPT_HOME environment variable. Within this base, each workspace is assigned a dedicated subdirectory inside stores/ based on its 16-character hexadecimal project ID.
Sources: crates/chkpt-core/src/config.rs:18-35, crates/chkpt-plugin/skills/chkpt/references/store-layout.md:5-7
The diagram shows the hierarchical structure from the root storage directory down to project-specific components.
Sources: crates/chkpt-core/src/config.rs:38-65, crates/chkpt-plugin/skills/chkpt/references/store-layout.md:9-17
Core Storage Components
Metadata Catalog (catalog.sqlite)
The central authority for the store is a SQLite database named catalog.sqlite. It manages snapshot metadata, flattened file manifests, and the indexing of blobs within data packs.
Sources: crates/chkpt-plugin/skills/chkpt/references/store-layout.md:19-20
| Table | Description | Key Fields |
|---|---|---|
snapshots | High-level metadata for checkpoints. | id, created_at, root_tree_hash, stats |
snapshot_files | Flattened manifest of files per snapshot. | snapshot_id, path, blob_hash, size, mode |
blob_index | Mapping of content hashes to pack locations. | blob_hash, pack_hash, size |
Sources: crates/chkpt-plugin/skills/chkpt/references/store-layout.md:33-58
Content Addressing and Packs
- Packs (
packs/): Contains compressed data blobs. When new files are saved, they are compressed with LZ4 and appended to pack files. Theblob_indexin the catalog tracks which pack contains a specific hash. - Trees (
trees/): Stores content-addressed tree nodes representing the directory structure. These nodes use a 2-character prefix sub-directory strategy (e.g.,trees/a3/...) to avoid directory entry saturation.
Sources: crates/chkpt-core/src/config.rs:68-72, crates/chkpt-core/src/ops/save.rs:120-135, crates/chkpt-plugin/skills/chkpt/references/store-layout.md:78-90
Local Workspace Cache (index.bin)
The index.bin file acts as a metadata cache for the current workspace. It stores file metadata (mtime, size, inode) to allow the save operation to skip hashing for files that haven't changed since the last checkpoint.
Sources: crates/chkpt-core/src/ops/save.rs:98-105, README.md:10-11
Store Initialization and Safety
When a project store is initialized, the StoreLayout ensures all necessary subdirectories exist. On macOS, a .metadata_never_index file is created to prevent Spotlight from indexing the store, which avoids CPU spikes during bulk write operations.
The initialization flow ensures the environment is ready for content-addressable storage.
Sources: crates/chkpt-core/src/config.rs:75-97
Data Relationships
The relationship between snapshots, their manifests, and the physical storage of data is managed through the project ID and content hashes.
Entity Relationship Diagram showing how snapshots link to physical file data via the catalog.
Sources: crates/chkpt-plugin/skills/chkpt/references/store-layout.md:33-58, crates/chkpt-core/src/ops/save.rs:175-195
Conclusion
The Storage Directory Layout provides a structured environment where metadata (SQLite) and content (Packs/Trees) are decoupled. By using project IDs derived from workspace paths and implementing content-addressed storage, chkpt achieves efficient deduplication and rapid incremental updates while maintaining a clean separation of data for different projects.