Pi Auto Compact

Pi Auto Compact adds early, configurable context compaction to Pi without interrupting active work.

It uses Pi's native compaction API and summary format. It does not replace Pi's summarizer, rewrite session history, or make a second model call outside Pi's compaction flow.

What is missing in native Pi

Pi already protects sessions from context overflow. Native automatic compaction runs when estimated context usage exceeds contextWindow - reserveTokens, and Pi lets users configure the response reserve and the amount of recent context to keep.

That native behavior does not provide an early percentage trigger, a session-only toggle, or an interactive settings panel. Pi Auto Compact fills those gaps while leaving native compaction available as a final safety net.

Capability	Native Pi	Pi Auto Compact
Automatic trigger	Near the model limit, based on reserved response tokens	At a configurable percentage of context usage
Manual compaction	/compact	Unchanged
Summary generation	Pi's native compaction prompt and session format	Uses the same native flow with optional supplemental guidance
Session-only control	No dedicated toggle	/auto-compact
Interactive configuration	Settings file	/auto-compact-config TUI panel
Active tool work	May compact at its own threshold	Waits until the agent settles, so it never interrupts work

Install

pi install npm:@thunstack/auto-compact

Try it for one Pi run without installing:

pi -e npm:@thunstack/auto-compact

Install directly from GitHub:

pi install git:github.com/aashishd/pi-auto-compact-plugin

Pi packages execute with your full system permissions. Review third-party extension source before installing it.

Version 0.2.1 requires Pi and Pi TUI 0.84.2. The exact version requirement keeps the extension's non-destructive eligibility check synchronized with Pi's native compaction rules.

Commands

Command	Purpose
/auto-compact	Toggle auto-compaction for the current session without changing the global startup default
/auto-compact-config	Open the settings panel in Pi's interactive terminal UI

The settings command requires TUI mode. The compaction behavior itself also works in non-interactive modes.

Settings and defaults

Global settings are stored in $PI_CODING_AGENT_DIR/auto-compact.json, or ~/.pi/agent/auto-compact.json when that environment variable is unset. The file is created only after a setting is saved. Until then, in-memory defaults are used.

Setting	Default	Scope	Accepted values	Purpose
enabledAtSessionStart	true	Global startup default	true or false	Sets whether new and forked sessions start with the extension active
Active in current session	Startup default	Current session	true or false	Controlled by /auto-compact; restored on reload or resume and never written to global config
thresholdPercent	60	Global	Integer 1 through 99	Compacts only when context usage is strictly greater than this percentage
autoResume	true	Legacy	true or false	Retained so existing config files remain valid. Automatic compaction never interrupts or resumes work.
resumptionInstruction	Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step.	Legacy	Any string	Retained so existing config files remain valid. Automatic compaction never queues this message.
waitForTurnEnd	true	Fixed safety setting	true only	Compaction starts only after the agent settles, so it cannot abort active work.
additionalCompactionInstruction	Preserve unfinished work and exact details required to resume safely.	Global	Any string	Appends guidance to Pi's native compaction prompt; blank uses only the native prompt

Equivalent config file:

{
  "version": 1,
  "enabledAtSessionStart": true,
  "thresholdPercent": 60,
  "autoResume": true,
  "resumptionInstruction": "Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step.",
  "waitForTurnEnd": true,
  "additionalCompactionInstruction": "Preserve unfinished work and exact details required to resume safely."
}

Use /auto-compact-config instead of editing the file when TUI mode is available. Saves are written atomically with owner-only permissions.

How it behaves

1. After Pi has fully settled, the extension reads the active model's context usage.
2. Above the configured threshold, it applies Pi 0.84.2's native cut-point rules to the active branch using Pi's effective keepRecentTokens setting.
3. If no history is eligible, it does not call ctx.compact(). Eligibility is checked again after later work settles.
4. When eligible history exists, it requests Pi's native compaction flow while Pi is idle and disarms until usage returns to or below the threshold.
5. A failed attempt stays disarmed at the current usage level, preventing a retry loop. Session replacement or reload also invalidates stale callbacks.

Pi's public compaction API aborts an active run before summarizing. This extension calls it only after Pi has settled, so it does not create an abort error or an artificial continuation message.

Interaction with native auto-compaction

This extension does not disable Pi's built-in threshold or overflow recovery. With the default 60% trigger, it normally compacts before Pi reaches its native reserve boundary. A long uninterrupted tool loop continues under Pi's built-in overflow protection until it settles. If native compaction runs first, Pi handles that event normally.

Pi's native compaction settings still control how much recent context is kept and how much response space is reserved. The extension reads the effective native recent-context setting before every above-threshold eligibility decision, including trusted project overrides.

Uninstall

pi remove npm:@thunstack/auto-compact

Removing the package does not delete ~/.pi/agent/auto-compact.json. Delete that optional settings file separately if you no longer want it.

Development

npm install
npm run check

npm run check type-checks the extension, runs the behavior tests, and previews the npm tarball. Publishing also runs the same checks through prepublishOnly.

License

MIT