pi-compaction-model

Fork: a fork of JMHSV/pi-compaction-model with minor changes. Original author: JMHSV.

A minimal extension for Pi Coding Agent that lets native compaction use a dedicated model and thinking level.

It does not introduce a new summarization pipeline. It calls Pi's exported compact() implementation with the configured model, preserving Pi's native:

• prompts and structured summary format
• cut-point and recent-message retention behavior
• iterative previous-summary updates
• split-turn summaries
• file-operation tracking
• output-token budgeting
• /compact focus instructions

If the configured model is unavailable or fails, the extension returns control to Pi, which compacts with the active conversation model.

Install

From GitHub:

pi install git:github.com/linuxtextadventurer/pi-compaction-model@main

Restart Pi after installation, or use /reload.

Configure

Add compactionModel to ~/.pi/agent/settings.json:

{
  "compactionModel": {
    "model": "openai-codex/gpt-5.6-terra",
    "thinkingLevel": "medium"
  }
}

model must be a model known to Pi in provider/model form.

Supported thinking levels are:

off, minimal, low, medium, high, xhigh, max

Omit thinkingLevel to use the provider default.

Select which compactions to route

By default the configured model handles all native compaction reasons:

• manual — /compact
• threshold — automatic context-threshold compaction
• overflow — overflow recovery before retry

Use reasons to handle only a subset:

{
  "compactionModel": {
    "model": "google/gemini-2.5-flash",
    "thinkingLevel": "low",
    "reasons": ["threshold", "overflow"]
  }
}

An empty reasons array disables routing without removing the configuration. You can also use "enabled": false, or set "compactionModel": false in trusted project settings.

Extra request headers

Some models only accept requests carrying app attribution headers. For example, OpenRouter free variants restricted to registered agentic harnesses require a referer from an approved app domain. Use headers to forward extra HTTP headers to the summarization request:

{
  "compactionModel": {
    "model": "openrouter/thinkingmachines/inkling-small:free",
    "headers": {
      "HTTP-Referer": "https://openclaw.ai"
    }
  }
}

headers must be an object mapping header names to string values. Configured headers override headers resolved from provider authentication.

Retries before fallback

Compaction failures fall back to Pi's active model. Use retries to attempt the configured model again before falling back, and retryDelay to wait between attempts:

{
  "compactionModel": {
    "model": "openrouter/vendor/model",
    "retries": 3,
    "retryDelay": 5
  }
}

retries is the number of attempts made after the first failed attempt and must be a non-negative integer. retryDelay is the wait in seconds after each failed attempt and must be a non-negative number (fractional values allowed). Without retries, the request is made exactly once and a failure falls back immediately. An aborted compaction stops retrying and falls back immediately.

Project overrides

A trusted project's .pi/settings.json can override individual global fields:

{
  "compactionModel": {
    "model": "anthropic/claude-sonnet-4-5"
  }
}

Project fields are shallow-merged over the global compactionModel object. Untrusted project settings are ignored.

Coexisting with other compaction extensions

Multiple extensions can handle session_before_compact, and the last extension that returns a compaction result wins. Avoid configuring two extensions for the same reason.

For example, to use Smart Compact manually and this extension only for automatic native compaction:

{
  "smartCompact": {
    "autoTrigger": false
  },
  "compactionModel": {
    "model": "openai-codex/gpt-5.6-terra",
    "thinkingLevel": "medium",
    "reasons": ["threshold", "overflow"]
  }
}

The resulting routing is:

Event	Handler
/smart-compact	Smart Compact
/compact	Pi native compaction with the active model
Automatic threshold	Pi native compaction algorithm with the configured model
Overflow recovery	Pi native compaction algorithm with the configured model
Configured-model failure	Pi native fallback with the active model

Failure behavior

The extension logs a warning and falls back to Pi's active model when:

• the configuration is invalid
• the model cannot be found
• authentication cannot be resolved
• the compaction request fails or is cancelled

Pi currently resolves authentication for the active conversation model before firing the compaction extension hook. Consequently, the active model must also have valid authentication even when a dedicated compaction model is configured.

Development

bun install
bun run check

License

MIT