pi-compactor

Pi extension that lets the LLM manage its own context compaction. The model decides when to compact based on task state, not fixed thresholds. Context hints keep it aware of usage without automatically triggering compaction; Pi's built-in threshold remains the final safety net.

Installation

Requires Pi 1.2.0 or later, which identifies custom-message runs during startup.

pi install npm:@nijaru/pi-compactor

How it works

1. As context fills, pi-compactor injects a small usage hint such as [ctx 128k/1m].
2. The model calls the compact tool at a genuine task boundary, with optional preservation instructions and an explicit continueAfterCompaction choice.
3. Pi reloads the session with the summary. If unfinished work remains or a final response is needed, the extension starts one hidden recovery turn after the active run settles; otherwise it stops without creating extra work.

The first hint is at 50% for context windows up to 128k, or about 128k tokens for larger windows. Later hints are throttled by both percentage and token deltas. A [>200k] marker indicates that the context has crossed the higher-cost range; it does not trigger compaction. Pi's own automatic threshold is controlled by compaction.reserveTokens in Pi's settings.json; this extension does not add another threshold.

Configuration

Use a cheaper/faster model for compaction summaries via --compaction-model:

pi --compaction-model openrouter/deepseek/deepseek-v4-flash

Or configure an ordered fallback chain in compaction-policy.json:

{
  "models": [
    "openrouter/deepseek/deepseek-v4-flash",
    "anthropic/claude-haiku-4-5"
  ]
}

The project file is <pi-config-dir>/compaction-policy.json (normally .pi/compaction-policy.json); the global file is Pi's agent directory (normally ~/.pi/agent/compaction-policy.json). Project policy is read only when Pi reports the project as trusted or has an explicit saved trust decision. A policy file alone does not opt an untrusted repository into sending summaries to a remote model. SDK users with a custom agent directory can set PI_COMPACTOR_AGENT_DIR explicitly; normal Pi sessions derive the active directory from the session manager. Resolution order is:

1. --compaction-model
2. the trusted project file
3. the global file
4. Pi's default compaction model

Configured models are retried only for transient failures. Empty summaries, permanent failures, invalid selectors, and missing authentication fall back to the next configured model and finally Pi's default. When the companion pi-provider-compaction extension is installed, leave compaction-model unset so its provider-native adapter can own the saved compaction details. Without a provider-native adapter, Pi's default compaction path remains available.

Development

Run bun install and bun run check (tests and typecheck). Pi loads the TypeScript source directly; no build step is needed.

License

MIT