pi-auto-compact

Pre-turn auto-compaction extension for pi. Proactively manages context window usage to prevent overflow errors.

The Problem

Pi's default auto-compaction only checks after agent_end. This means context can overflow during long multi-tool turns before compaction triggers.

Strategy

This extension checks tokens at three points:

1. Pre-turn: Before sending any request to the LLM (turn_start)
2. Mid-turn: After tool execution, before follow-up LLM calls (turn_end)
3. Emergency: Synchronous truncation in the context event as a last resort

It also handles the session resume case: when an existing session is reopened above the threshold, compaction kicks off as soon as the session starts.

Continuing After Auto-Compaction

ctx.compact() aborts the running agent internally, so without a nudge the session would sit idle once the summary is written. After every auto-triggered compaction this extension sends a short English follow-up user message to make pi resume the in-flight task. The exact wording depends on which check fired (pre-turn, mid-turn, emergency, or session-resume).

The follow-up is suppressed in two cases:

• The user ran /compact manually — the callback path used here only fires for compactions this extension started, so manual compaction is never touched.
• The agent is no longer idle when the summary finishes, e.g. the user already typed something or another extension started a turn while summarising. Their input acts as the kickoff and we stay quiet.

Compaction Strategies

Strategy	Description
keep-recent	Keep only the most recent messages (default)
keep-bookends	Keep oldest + newest messages, compact the middle
summarize-all	Remove everything except the last user message

Configuration

Use /auto-compact to open the interactive settings menu:

/auto-compact              # Open settings menu
/auto-compact status       # Show current status
/auto-compact reset        # Reset to defaults

Settings

Setting	Default	Options
Auto-compact threshold	90%	80%, 85%, 90%, 95%
Keep recent budget	15%	5%, 10%, 15%, 20%
Strategy	keep-recent	keep-recent, keep-bookends, summarize-all
Debug logging	off	on/off

Example

For a 200K context window model:

• Compact at 180K tokens (90%)
• Keep 30K recent tokens (15%)

Install

As a pi package:

pi install npm:@capyup/pi-auto-compact

Or via git:

pi install git:github.com/capyup/pi-auto-compact

Or run directly:

pi -e ./extensions/auto-compact.ts

How It Differs from Pi's Default

Aspect	Pi Default	This Extension
Check timing	After agent_end only	Before requests + after tools
Overflow protection	None	Emergency truncation
Mid-turn handling	None	Checks after each tool batch
Auto-continue	No	Yes — sends an English follow-up nudge after auto-compaction

License

MIT