pt-compact

A Pi extension that triggers context compaction at a configurable usage percentage and uses a configurable model for Pi's native compaction algorithm.

Features

• Automatically compacts context after the configured percentage is reached.
• Supports Pi's built-in /compact [instructions] command.
• Uses one configurable model for both extension-triggered and built-in compaction.
• Keeps the active conversation model unchanged.
• Resumes the current task after extension-triggered compaction.
• Keeps Pi's built-in automatic compaction enabled as an overflow safety net.

Install

Install from npm after the package is published:

pi install npm:pt-compact

Try a local checkout without installing it:

pi -e .

Configure

Create ~/.pi/agent/pt-compact.json:

{
  "compressionModel": "google/gemini-2.5-flash",
  "compressionThinkingLevel": "low",
  "thresholdPercent": 80
}

compressionModel is required and must use the exact provider/model identifier shown by Pi's model list. The provider must already be authenticated in Pi.

compressionThinkingLevel is optional and defaults to low. Supported values are off, minimal, low, medium, high, xhigh, and max; Pi/provider model capabilities may clamp the selected level.

This release requires Pi 0.85.1 or newer.

thresholdPercent is optional and defaults to 80. It must be greater than 0 and less than 100.

Reload Pi after changing the file:

/reload

Usage

Automatic compaction runs after a model turn when context usage reaches the configured percentage. After compaction, the extension asks Pi to continue the current task without repeating completed tool calls.

Manual compaction uses Pi's existing command and ignores the percentage threshold:

/compact
/compact Focus the summary on unresolved errors and modified files.

The extension calls Pi's exported compact() function. It does not implement or replace Pi's summary format, cut-point selection, retained-message handling, or file-operation tracking.

Failure behavior

If extension-triggered compaction fails, the extension:

1. Reports the error.
2. Leaves the active conversation model unchanged.
3. Suppresses another extension-triggered attempt until the next user input.
4. Continues the current task using the existing context.

Pi's own automatic compaction should remain enabled. It provides threshold and overflow recovery if context grows beyond Pi's native safety boundary:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

The extension never edits Pi's settings.json.

If the configured compression model fails during Pi's own automatic threshold or overflow compaction, the extension allows Pi to fall back to its active model so Pi's native recovery remains available.

Notes

• Context usage is based on Pi's ctx.getContextUsage() estimate.
• Automatic checks run at turn_end, after completed tool results have been recorded.
• Compaction is lossy. Pi keeps the full session history in its JSONL session file.
• The configuration is global. Project-specific configuration and a settings UI are intentionally not included.

Development

Requires Node.js 22.19 or newer.

npm test
npm run check

License

MIT