pi-gate-compact

A pi extension that compacts the context by percent of the window or by an absolute token count. Both triggers are always active and whichever one is hit first — that is, the lower one — wins.

With 90 / 300000: a 1M-token model compacts at 300,000 tokens; a 256k model compacts at 230,400.

Configuration

File: ~/.pi/agent/pi-gate-compact.json (or $PI_CODING_AGENT_DIR/pi-gate-compact.json).

{ "percent": 90, "tokens": 300000 }

• Missing file: defaults are percent = 90 and tokens = 300000. A missing key uses its own default.
• percent: a number greater than 0 and at most 100 (decimals allowed).
• tokens: a positive integer.
• Any other key, invalid JSON, or an out-of-range value disables the trigger and shows an error until the file is fixed.
• The file is re-read on every evaluation; no /reload needed.

Behavior

• Mid-run: at the end of a turn that called tools, if the context passed the trigger, the extension summarizes the history and pi applies the compaction inside the turn_end boundary. The run is never aborted and continues with the compacted context, so extensions that treat an aborted run as the user pressing Escape (for example pi-goal-x, which pauses the goal) are not affected. The summary uses pi's own summarization with the current model and pi's compaction.reserveTokens / keepRecentTokens (including modelOverrides). This compaction does not emit session_before_compact / session_compact.
• Final turn: a run that is finishing is never compacted. Compaction happens before the next prompt.
• Before sending a prompt: if the context (plus the prompt) passes the trigger, compact first. If compaction fails, the prompt is sent anyway, with a warning, and the trigger stays suspended until the context drops below the limit.
• If a mid-run compaction fails, the run keeps going and the trigger stays suspended the same way. Pressing Escape during the summary aborts the run and drops the compaction.
• Honors pi's compaction.enabled = false: with automatic compaction off, the trigger is inactive too.
• pi's native trigger (window − reserveTokens) keeps working as a safety net.

Command

/gate-compact prints the configuration, the effective trigger for the current model, the context usage, and the state (armed, compacting, suspended, disabled).

Installation

From npm:

pi install npm:pi-gate-compact

Or from a local checkout, loaded straight from the path without copying:

pi install ~/dev/pi-gate-compact

Pin a version with pi install npm:[email protected], or try it for a single invocation without writing to settings with pi -e npm:pi-gate-compact.

Requires pi 1.2 or later (developed and tested against 1.2.0). @earendil-works/pi-coding-agent is declared as a peer dependency and supplied by pi itself, so the package does not ship a copy of it.

A pi-profiles preset whose packages does not list this entry removes it on the next apply.

Development

npm install
npm run check   # biome + tsc + vitest

Publishing

npm publish runs npm run check first (prepublishOnly) and ships only src/, README.md and LICENSE:

npm pack --dry-run   # inspect the tarball
npm version patch    # or minor/major
npm publish

The pi-package keyword makes the package discoverable in the pi package gallery.