$ cat ~/map/self-compact-pi-agent.md
Self Compact
Gives autonomous pi agents their own context gauge — notice and warning lines first, then a hard cutoff where only self_compact runs.
extensions✓ Sep 21
Facts
- GitHub Stars
- ★ 74
- Forks
- 20
- license
- MIT
- npm / mo
- —
- last push
- Sep 20, 2026
install
Clone the repo, put a provider key in .env (OPENROUTER_API_KEY recommended), and launch with just run --model <model-id>; just demo walks a full cycle with a scripted model and no API key. Prerequisites: pi v0.85.1, Node 24+, and just.## TL;DR
A pi extension that hands long-running agents their own context gauge: a hint at the notice line, a handoff-note instruction at the warning line, and a hard cutoff where only self_compact runs — the note it writes comes back verbatim as the next message after compaction.
## Key points
- $A four-phase cycle: notice when usage crosses --compact-soft-at, warning at --compact-at, forced at warning plus --compact-buffer (capped at 90 percent of the window), then handoff — the agent calls self_compact with a note_to_self, compaction runs once idle, and the note returns verbatim with tools restored.
- $Guidance never persists: hints are injected into the next model call and dropped, so the only messages in saved context are your prompts and the returned note.
- $Two views of one gauge: the 20-cell terminal footer with cached, uncached, notice, warning, and cutoff markers belongs to you, while the agent calls view_context to read used tokens, percent, thresholds, and tokens left as JSON whenever it wants.
- $Recovery is built in: if compaction fails or is cancelled, the note and the lock survive and the extension retries; /self-compact-now or /compact can finish the job, reload, resume, and /tree rebuild the handoff from the session, and an answered handoff never restarts.
- $Thresholds tune per run: shipped defaults put notice, warning, and hard cutoff at 10, 20, and 30 percent of the model window, and overrides like just soft=5% warn=8% buffer=2% trigger cycles sooner — keep the notice line above pi's retained recent history (keepRecentTokens, 20k by default).
## FAQ
Q Why not rely on pi's built-in compaction?
Built-in compaction is reactive: it fires near the wall with a generic summary prompt, the agent gets no warning, and nothing carries the agent's own what-I-was-about-to-do across the boundary. Self Compact makes the thresholds visible and has the agent write the handoff note itself at a clean checkpoint.
Q Does the agent see the gauge, or is it just for the human?
Both, on separate surfaces. The terminal footer belongs to the human; the agent asks view_context and receives the same numbers — used tokens, percent, thresholds, tokens left — as JSON, so it never has to guess where it stands.
## References
## Related entries
$ big-pi
Model-driven compression that summarizes completed phases into tiered blocks while Pi's JSONL transcript stays authoritative and untouched.
$ pi-rolling-compaction
Trigger pi's built-in compaction once context hits a configurable threshold (default 50% of the window) so large-context models get a continuously-maintained rolling summary instead of a near-full cliff-edge.
$ pi-ttft
Footer HUD that times the first token and names the culprit — network or server — when one clearly dominates.
## Guides
Last updated: Sep 21, 2026