pi-checkpoint

A pi extension. When a session's context is nearly full it asks the model to save its progress with a save_progress tool, writes that to a per-session file, and puts it back into the context after the next compaction. It works beside pi-vcc or pi's built-in compaction; it does not replace either.

• Progress files: ~/.pi/agent/checkpoints/<project folder>/<session id>.md. One per session, so a new session in the same folder never inherits an old one's progress.
• Settings: ~/.pi/agent/checkpoint.json (enabled, thresholdPercent, compactAfterSave, dir, file, maxChars, instruction). Missing keys use the defaults in src/core.js.
• Commands: /checkpoint (ask the model to save now), /checkpoint show, /checkpoint on|off.

It never compacts a running agent, because that aborts the run. Mid-run the cut is pi's own threshold compaction; set a per-model compaction.modelOverrides reserve in pi's settings.json if you want that to follow the save closely on a large-context model. Keep the gap between the checkpoint threshold and pi's trigger well above one save + compaction + restore (a few thousand tokens): if the context is still over the threshold right after a cut, the extension warns once and stops asking.

With pi-vcc, add both of this extension's message types to its skipCustomTypes so they stay out of its summaries (the restore is re-injected by this extension anyway): "skipCustomTypes": ["progress-checkpoint-request", "progress-checkpoint"].

Try it

pi -e /path/to/pi-checkpoint/src/index.ts

Tests

npm test                    # unit tests for the decision logic
npm run test:integration    # the real extension inside pi, against a scripted fake model

Design and plan: docs/superpowers/.