Pi Auto Compact

Pi Auto Compact adds early, configurable context compaction to Pi between model responses.

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 | | Tool-driven work | May compact at its own threshold | Waits for the current model response and its tool calls, then compacts before the next response and resumes unfinished 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.3 is tested with Pi and Pi TUI 0.84.4. It uses Pi's host-provided packages, as required by Pi's package guidance.

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 | Global | true or false | Resumes unfinished tool-driven work after a compaction attempt stops the active agent loop between model responses | | resumptionInstruction | Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step. | Global | Any string | Sets the follow-up message that resumes stopped tool-driven work. Blank disables the follow-up. | | waitForTurnEnd | true | Fixed safety setting | true only | Prevents compaction during a model response or tool call. Compaction starts at the completed response boundary. | | 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 each model response and its tool calls finish, the extension reads the active model's context usage.
2. Above the configured threshold, it applies Pi's public 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(). It checks again after the next model response.
4. When eligible history exists, it requests Pi's native compaction flow before the next model response.
5. Pi's public compaction API stops the current agent loop before summarizing. When the completed response used tools, autoResume queues one follow-up after success or failure so unfinished work continues.
6. A failed attempt stays disarmed for the unchanged session branch, preventing a retry loop. It retries after later work advances the branch, even if usage remains above the threshold. Session replacement or reload also invalidates stale callbacks.

The extension never stops a model response or tool call in progress. A compaction can end the surrounding agent run between responses, so the default auto-resume behavior is required for uninterrupted tool-driven work.

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. It checks after every model response in a tool-driven run. 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