Skip to main content
Entire writes checkpoints into your own Git repository, in objects separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage.
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. Change this when checkpoint history should follow a different storage or access boundary:

​
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 is the default. Since Entire CLI 0.10.0, entire enable writes it during a first-time setup and no longer asks you to choose. A repository you enabled before 0.10.0 stays branch-based until you change it. Each ref points at a commit whose tree root is that one checkpoint’s contents, so Entire pushes and fetches a single checkpoint without moving the rest, and multiple agents can save checkpoints at once without competing to update one branch. Under branch-based storage, each checkpoint sits at <first two characters of the ID>/<rest of the ID>/ in the branch tree, so every condensation rewrites one branch tip and the whole history travels together on push.

​
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

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.