@easiest-ai/pi-compaction-manager

A companion extension for pi that makes auto-compaction configurable and improves compaction summaries.

pi's auto-compaction is built around each model's full context window and generic summarization instructions. For most models this is adequate, but large-context models in long sessions present a different problem: compaction fires late, context grows unwieldy, and there is no control over when it triggers, how large the context gets, or what the summary keeps. Bounding the context also avoids unnecessary costs from cache hits on long contexts and improves working context density. This extension provides that control through an interactive panel mirroring pi's /settings.

Approach

The extension works with pi's existing machinery. It hooks the same lifecycle events (session_start, model_select, session_before_compact) and adjusts the same settings pi reads (contextWindow, reserveTokens, keepRecentTokens). Configuration persists to the same files pi maintains: ~/.pi/agent/settings.json and ~/.pi/agent/models.json. The /compaction panel uses the same TUI components as /settings (SettingsList, SelectList, DynamicBorder).

Defaults are unobtrusive: 128k context cap, 64k compaction trigger. Per-model overrides handle models that need different values.

Features

• Configurable max context: caps the model's contextWindow (e.g. 128k for a model that defaults to 1M).
• Configurable compaction target: sets reserveTokens so compaction triggers at a chosen token count (e.g. 64k), not near the window limit.
• Better compaction summaries: injects custom summarization instructions via session_before_compact to preserve file paths, error messages, decisions, task state, and environment details.
• /compaction command: interactive settings UI mirroring /settings. Also accepts text args for scripting.
• Per-model overrides: set maxContext / compactionTarget per provider/modelId.

Installation

pi install npm:@easiest-ai/pi-compaction-manager

Or from git:

pi install git:github.com/easiest-ai/pi-compaction-manager

Or try it without installing:

pi -e npm:@easiest-ai/pi-compaction-manager

Requirements

• pi >= 0.83.0

Configuration

Reads from ~/.pi/agent/extensions/compaction-config.json, created with defaults on first load.

{
  "maxContext": 128000,
  "compactionTarget": 64000,
  "keepRecentTokens": 20000,
  "enabled": true,
  "modelOverrides": {
    "openrouter/z-ai/glm-5.2": { "maxContext": 128000, "compactionTarget": 60000 }
  }
}

Setting	Type	Default	Description
maxContext	number	128000	Maximum context window in tokens. Models with larger windows are capped.
compactionTarget	number	64000	Context token count at which auto-compaction triggers.
keepRecentTokens	number	20000	Recent tokens kept unsummarized during compaction.
enabled	boolean	true	Whether auto-compaction is enabled.
modelOverrides	object	{}	Per-model overrides keyed by provider/modelId.

How it works

On session_start:

1. Caps all models in the registry to maxContext (or the per-model override), in-memory immediately.
2. Writes reserveTokens (= maxContext − compactionTarget) and keepRecentTokens to ~/.pi/agent/settings.json under compaction. Run /reload to apply.
3. Writes contextWindow override to ~/.pi/agent/models.json for the active model.

On model_select: applies the cap to the selected model and persists its override.

On session_before_compact: injects custom summarization instructions (auto-compaction and manual compaction, not overflow recovery).

Reserve tokens

reserveTokens controls when auto-compaction triggers. pi fires compaction when:

contextUsage >= contextWindow − reserveTokens

With maxContext = 128000 and compactionTarget = 64000, reserveTokens = 64000 and compaction triggers at ~64k tokens.

Usage

Interactive UI

/compaction

Settings panel for maxContext, compactionTarget, keepRecentTokens, enabled, reset, and current context usage. Requires TUI mode.

Text mode (scripting)

/compaction maxContext 128000
/compaction target 60000
/compaction keepRecent 15000
/compaction enabled true
/compaction reset

Valid keys: maxContext, target, keepRecent, enabled, reset.

License

MIT