disler / self-compact-pi-agent

# Self Compact. A Pi agent that compacts its own context
> **Long-running (out-loop) agents cannot not wait for a human or 100% token window or to fire compaction.**
> A standalone Pi extension for autonomous, out-loop coding agents.
📺 Watch this video to get the full breakdown of this codebase: **Self Compact on YouTube**
The agent watches its own context gauge. At the notice line it gets a hint, at the warning line it is told to write a handoff note, and at the hard cutoff every tool except `self_compact` is blocked. It writes a `note_to_self`, the context is compacted with a prompt you control, and the exact note comes back as the next message. **No human message, no lost intent, no restarted work.**
## Try It Out
Every recipe lives in the `justfile`. Two commands and one prompt to watch an agent compact itself:
 [code] 
3\. Paste this prompt and answer `yes` each time the agent stops:
 [code] 
Every chunk adds tens of thousands of tokens to the context. Watch the footer gauge climb past the `~` notice marker and the `!` warning marker, then see the agent write its `note_to_self`, call `self_compact`, and carry on from the returned note. The shipped defaults are notice 10%, warning 20%, hard cutoff 30% of the model window (see `apps/self-compact/extensions/self-compact/defaults.ts`); on a 1M-token model that is about 105k / 210k / 315k tokens. To reach a cycle sooner, lower them: `just soft=5% warn=8% buffer=2% run --model openrouter/deepseek/deepseek-v4.1-flash` (about 52k / 84k / 105k). Keep the notice line well above Pi's retained recent history (`keepRecentTokens`, 20k by default), otherwise a compaction has nothing to cut. Inside Pi, `/self-compact-info` prints the live numbers at any time, asking the agent to call `view_context` shows you what it sees, and `just demo` walks the whole cycle with a scripted model and no API key. If OpenRouter answers with 429 rate-limit errors for that model, any other Pi model id works the same way (`pi --list-models deepseek` lists the other DeepSeek flash slugs).
---
## Install
### Agentic Install
 [code] 
### Manual Install
**Prereqs:** Pi coding agent v0.85.1, Node 24+, just, and a provider key in `.env` (`OPENROUTER_API_KEY` recommended, see `.env.sample`; only live runs need it).
 [code] 
There are no npm dependencies to install for the extension itself: Pi's loader supplies its packages at runtime and Node 24 strips the types for the tests.
---
## Why this exists
Every turn of an autonomous agent re-sends its whole history. Quality decays as the window fills (context rot) and every call costs more than the last. Pi ships compaction, but it 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. A summary written by a bystander is how finished work gets redone.
The fix is to hand the agent the gauge and the hand-off. **Thresholds it can see, a note it writes itself, and a compactio