Skip to main content
Entire stores checkpoints inside your own Git repository, separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage. Most of this happens behind the scenes, so your workflow stays the same: you create, search, explain, and resume checkpoints with the same Entire commands regardless of how they are stored.
We verified this page against Entire CLI 0.10.2. Run entire version to check what you have installed.

​
Store Checkpoints with Your Code

This is the default and needs no configuration. Entire stores checkpoint data in the same Git repository as your code and pushes it when you push, which keeps the commit, the checkpoint, and the agent context together while leaving your normal Git history clean. In a repository with several remotes, Entire elects one checkpoint sync remote rather than copying checkpoints everywhere you push. entire status names the destination and counts checkpoints that have not reached it. This can be changed if you want your checkpoint and session storage history to reside elsewhere:

​
The Two Storage Backends

The backend controls how Git organizes checkpoint data. It is a separate question from which repository receives that data.

​
Ref-Based Storage

Ref-based storage (git-refs) is the default. It gives each new checkpoint its own Git ref, a named pointer inside your repository that Entire creates and manages for you. Each ref lives at refs/entire/checkpoints/<shard>/<id>, and Entire saves and retrieves each checkpoint independently. The benefit: With ref-based storage, pushes and reads stay fast even as your repository accumulates more agent history. Multiple agents can also save their work at the same time without competing to update a shared branch. Ref-based checkpoints use 26-character, time-sortable ULIDs, such as 01KVBJCWYA4YW6J5M9GP655HZN. Ref-based storage first shipped as an opt-in option in Entire CLI 0.8.42 and became the default in 0.10.0, where entire enable writes it during a first-time setup and no longer asks you to choose.

​
Branch-Based Storage

Branch-based storage (git-branch) keeps every checkpoint on a shared Git branch called entire/checkpoints/v1. Each checkpoint sits at <first two characters of the ID>/<rest of the ID>/ in the branch tree. The benefit: All checkpoint history lives on one branch you can check out, browse, or clone like any other branch. Branch-based checkpoints use 12-character hexadecimal IDs, such as a3b2c4d5e6f7. A repository you enabled before Entire CLI 0.10.0 uses branch-based storage and stays on it until you switch backends.

​
Find Which Backend a Repository Uses

The backend is named by checkpoints.primary.type in .entire/settings.json, or in .entire/settings.local.json when someone set it for their clone alone. An absent checkpoints block resolves to git-branch, which is why a pre-0.10.0 repository keeps branch storage without any setting naming it. Checkpoint storage is ordinary Git, so Git reads it without Entire installed. List the per-checkpoint refs:
Each line names one checkpoint, where <shard> is the last two characters of the ID and <id> is always the leaf. Check for branch-backed checkpoints too:
Output from both means the repository holds checkpoints in both formats, which is the expected state after a backend switch. To confirm what reached the remote, run git ls-remote origin 'refs/entire/checkpoints/*'.

​
Both Backends Stay Readable

Every reader routes by ID format, so one repository can hold both formats at once. This holds for the CLI, entire.io, and the Entire API. entire checkpoint list merges both backends and de-duplicates by ID. A new checkpoint goes to the configured backend, while a backfill that adds a transcript, summary, or attribution to an existing checkpoint lands in whichever backend already holds it.

​
Switch Backends

To enable ref-based storage in a new repository, run:
To enable it in an existing Entire-enabled repository, run:
Both commands accept refs and branch, plus the canonical git-refs and git-branch that settings store. Add --local when the choice should apply only to your clone. A switch applies to new checkpoints. Checkpoints written before the switch stay exactly where they are and keep resolving through the routing above, so entire checkpoint list, entire checkpoint explain, attribution, and entire.io continue to serve them. Entire deletes nothing during a switch, and your commands and commit workflow do not change. Two things do change after a switch to ref-based storage. New checkpoint IDs become ULIDs instead of hex, and the pre-push hook starts pushing queued per-checkpoint refs instead of the entire/checkpoints/v1 branch. Leave that branch on the remote: it is where readers find every checkpoint captured before the switch.

​
Migrate Existing Checkpoints into Refs

Migration is optional, since the routing above already resolves branch-backed checkpoints under a ref-based backend. Migrate when you want the whole history in one format, or when you want to stop carrying the v1 branch.
Run the migration before you switch the backend to refs. The command refuses to run once ref-based storage is primary, because the refs are authoritative at that point and re-importing branch snapshots could only move them backwards.
The command wraps each checkpoint’s current tree in a fresh commit and points its ref at it, keeping the hex ID as the ref name. It does not rewrite the branch commits, and it does not delete the branch. It skips checkpoints it has already converted, so you can re-run it after more branch activity. Migrated refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next git push once ref-based storage is primary. Then switch and push:

​
Auto-Generate Checkpoint Summaries

Checkpoint metadata can carry a summary generated at commit time. Enable it with strategy_options.summarize.enabled:
.entire/settings.json
Then choose the provider and model:

​
Where Storage Settings Are Saved

entire configure writes to .entire/settings.json by default, so the repository shares the setting. Add --local to write .entire/settings.local.json instead, which applies only to your clone and takes precedence over project settings. The checkpoints block is a selection, not a merged document: a checkpoints block in .entire/settings.local.json replaces the one in .entire/settings.json outright. The strategy_options keys merge by layer as usual. See Local, Project, and Global Settings for the full table.

​
Continue With

Store Checkpoints in Another Repository

Push checkpoint history to a repository separate from your code.

Keep Checkpoints Local

Capture checkpoints without pushing them anywhere.

Security and Privacy

See every location Entire writes to and what redaction covers.

Checkpoint Troubleshooting

Fix checkpoints that did not sync or landed in the wrong place.