pi-supercompact

A Pi extension for deliberate, loss-resistant context compaction.

It provides a focused pre-compaction checkpoint, configurable final confirmation for agent-driven requests, optional automatic supercompaction, one-shot and live-session no-confirm permission, a canonical full-context handoff, Pi native compaction, invisible handoff restoration, and conservative continuation of authorized work. No-confirm permission waives only the final confirmation dialog.

Requirements

• Pi 0.80.10 or later
• Node.js 22.19.0 or later for package development

Installation

From GitHub:

pi install git:github.com/arcanemachine/pi-supercompact

From npm after publication:

pi install npm:@arcanemachine/pi-supercompact

For local development:

pi -e ./src/index.ts

Commands

/supercompact
/supercompact run [extra context]
/supercompact force [extra context]
/supercompact agent-driven-allow
/supercompact agent-driven-allow-noconfirm
/supercompact agent-driven-allow-noconfirm-once
/supercompact agent-driven-deny
/supercompact abort
/supercompact auto-enable
/supercompact auto-disable

/supercompact opens a menu with preparation, force, automatic-supercompact controls, agent-driven permission controls, and abort. Preparation and force open a multiline editor for optional context.

Automatic controls affect only percentage-triggered work. Agent-driven controls grant permission for the public tool to request compaction. Neither control grants the other.

Automatic supercompact

Automatic supercompact is off by default. When enabled, it checks context usage after each completed assistant turn:

• At 80%, it starts the same careful preparation as /supercompact run.
• At 90%, it skips unfinished automatic preparation and starts the same immediate summary as /supercompact force.
• If usage first reaches 90%, it takes the force path directly.
• Automatic work does not open a confirmation dialog. /supercompact abort can cancel it before Pi starts native compaction.
• Automatic prompts preserve momentum: they prefer continue for clearly unfinished authorized work, retain the active objective and one exact next action, and stop only when work is complete, blocked, awaiting input or approval, or unsafe to continue.
• Each threshold is tried once until usage falls below the soft threshold or compaction completes. An abort or failure does not retry immediately.

Use /supercompact auto-enable or /supercompact auto-disable to override the setting for the live session. The choice survives /reload, but not a new, resumed, or forked session. It does not write configuration, and disabling it does not cancel automatic work already underway.

Prepare normally

/supercompact run
/supercompact run preserve the accepted boundaries and continue implementation

run does not compact immediately. It:

1. Creates one pending preparation authorization.
2. Sends a hidden steering prompt for a focused refresh-and-close checkpoint.
3. Lets the agent finish already-authorized work that needs no new input, refresh relevant durable context, and verify or persist work when applicable.
4. Requires the agent to surface blockers or questions, choose whether work should continue, and name one exact next action.
5. Uses the configured global confirmation default, unless an explicit live-session agent-driven-allow or agent-driven-allow-noconfirm mode selects the behavior.
6. Starts the canonical summary and native compaction after confirmation or no-confirm authorization.

The checkpoint follows the active session's scope and rules. It does not assume that every session has a repository, files to edit, validation to run, or changes to commit.

If user input is required, the agent asks and waits. The one-off authorization remains pending across turns until it is used, canceled, denied, or replaced by session lifecycle activity.

Force immediately

/supercompact force
/supercompact force stop after compaction

force immediately starts the canonical summary and native compaction workflow. It bypasses preparation and final confirmation because the command itself is explicit user authorization. It remains available when agent-driven requests are denied.

Allow one agent-driven request without confirmation

/supercompact agent-driven-allow-noconfirm-once

agent-driven-allow-noconfirm-once arms the next valid agent-driven supercompaction without starting preparation or compaction itself. The user can then instruct the agent to complete the normal focused preparation and request supercompaction. The grant temporarily overlays denied or confirmation-required configured or live-session permission without changing it. While armed, the status is supercompact: agent-driven-allow-noconfirm-once 🗜️ .

The grant is consumed only after a valid request successfully queues canonical-summary work. Invalid arguments, unavailable tools, or a synchronous queueing failure leave it armed; once work is queued, a later abort or failure does not re-arm it. Consumption automatically reveals the prior configured or live-session permission and status.

If effective configured or /supercompact agent-driven-allow-noconfirm permission already bypasses confirmation, the command warns and does not arm a redundant grant. An explicit confirmation-required or denied session override can still be overlaid even when underlying configuration allows no-confirm requests.

The grant is in-memory only. Reloading, replacing, resuming, forking, or shutting down the session clears it, as do abort, agent-driven-deny, run, force, agent-driven-allow, and agent-driven-allow-noconfirm. The command refuses to arm while a preparation, confirmation, summary, or compaction workflow is active.

Abort before native compaction

/supercompact abort

abort cancels pending preparation, an armed one-shot grant, an open confirmation, or queued or active canonical-summary work before native compaction begins. It preserves configured and persistent live-session permission and does not change either tool schema. Calling it with no abortable workflow or one-shot grant reports No supercompaction is active. as an error.

Pi does not expose native compaction cancellation to extensions. Once native compaction begins, press Escape in the TUI or use the host's native cancellation mechanism when available.

Live-session agent-driven permission

• /supercompact agent-driven-allow permits agent-driven requests with final confirmation for the current live extension session.
• /supercompact agent-driven-allow-noconfirm permits agent-driven requests without the final confirmation dialog for the current live extension session.
• /supercompact agent-driven-allow-noconfirm-once temporarily permits one request without the dialog, then restores the effective configured or live-session mode.
• /supercompact agent-driven-deny revokes either persistent session mode and cancels an unused preparation, one-shot grant, or open confirmation.

agent-driven-allow, agent-driven-allow-noconfirm, and agent-driven-deny update session-local permission and never write configuration. A context-excluded custom session entry restores that persistent override and its status across /reload; it does not enter model context. agent-driven-allow-noconfirm-once uses only transient in-memory state and is cleared by reload. Starting a new process, creating or resuming a session, or forking discards all runtime permission and reapplies configured denied, confirmation-required, or no-confirm permission.

Confirmation-required permission lets an agent-driven request supercompaction but still requires final TUI or RPC confirmation. No-confirm permission is stronger authorization: an agent-driven request may queue the canonical summary and native compaction without another approval prompt. It skips only the dialog; preparation expectations, exact-next-action validation, concurrency and host-tool checks, summary validation, continuation constraints, bounded retries, compaction, filtering, restoration, and cleanup remain enforced.

A declined, canceled, revoked, busy, denied, unavailable, or confirmation-required headless request tells the agent what must happen next and not to retry automatically.

Configuration

Persistent confirmation, request permission, and automatic supercompact use an extension-specific JSON file:

{
  "requireConfirmation": true,
  "agentRequestsAllowed": true,
  "agentRequestsRequireConfirmation": false,
  "supercompact": {
    "enabled": true,
    "thresholdPercent": 80,
    "forceThresholdPercent": 90
  }
}

The global file is ~/.pi/agent/pi-supercompact.json. A trusted project may override it with <project>/.pi/pi-supercompact.json; a recognized project configuration is one complete overriding policy rather than a property-by-property merge. Project configuration is ignored for untrusted projects.

• requireConfirmation is the global confirmation default and defaults to true. It governs prepared run requests when no explicit allowed session mode selects the behavior.
• agentRequestsAllowed defaults to false and is the only property that grants persistent agent-driven permission.
• agentRequestsRequireConfirmation governs config-authorized agent-driven requests. When omitted, it inherits requireConfirmation.
• supercompact is optional. It enables automatic supercompact only when enabled is true. Its thresholds default to 80 and 90 when omitted. They must be finite percentages above 0 and below 100, with thresholdPercent below forceThresholdPercent.

For one Pi process, --supercompact-auto enables automatic supercompact and --no-supercompact-auto disables it. If both are supplied, the negative flag wins. Live /supercompact auto-enable or /supercompact auto-disable settings override flags; flags override trusted project or global configuration. These controls affect automatic triggering only, not the extension's tools or manual /supercompact commands.

With no live-session override:

requireConfirmation	agentRequestsRequireConfirmation	Prepared run	Config-authorized request
true	omitted	Confirm	Confirm
false	omitted	No confirm	No confirm
false	true	No confirm	Confirm
true	false	Confirm	No confirm

/supercompact agent-driven-allow and /supercompact agent-driven-allow-noconfirm explicitly override confirmation behavior for authorized agent-tool execution during the live session. /supercompact agent-driven-allow-noconfirm-once overlays either mode or configured policy for one successfully queued request without mutating it. /supercompact agent-driven-deny blocks unprepared requests but does not prevent the user from creating a later one-off run or no-confirm grant. /supercompact force always remains immediate and dialog-free.

Missing request permission remains denied. Confirmation properties never grant permission. A recognized property with a non-boolean value makes that configuration invalid; invalid configuration fails closed to denied requests with confirmation required and warns when UI is available.

Stable tools and authorization

The extension registers these tools once when it loads and keeps their schemas active throughout the extension session:

• supercompact — the public request interface
• record_supercompact_decision — internal canonical-summary workflow control

Tool visibility does not grant authority. The public tool checks effective session permission, an unused run grant, or an armed one-shot no-confirm grant; workflow and confirmation state; internal-tool availability; exact-next-action validity; UI capability when the active mode requires it; and authorization again at the last applicable boundary. The internal tool accepts a call only during the canonical-summary phase with a valid non-empty handoff, exactly one decision call, no other tool calls, and all confirmed stop constraints intact.

The extension never changes Pi's active tool selection to enforce permission. If the user or host excludes a required extension tool, the extension respects that choice. run and force fail before creating workflow state when required tools are unavailable, and explain that the tool must be re-enabled or the extension reloaded with its tools available. agent-driven-allow, agent-driven-allow-noconfirm, agent-driven-allow-noconfirm-once, and agent-driven-deny still update or arm session-local permission while reporting that execution remains unavailable. abort never changes the active tool selection.

How it works

The extension does not replace or customize Pi's native compaction summary. It creates its own canonical working-memory handoff, then calls native compaction without custom instructions.

Pi may automatically compact after the canonical summary turn if that turn crosses the configured threshold. A successful automatic compaction satisfies the workflow, so the extension does not compact twice.

Pi also has built-in automatic compaction. To make supercompact the only automatic compactor, disable Pi's compaction in settings.json:

{
  "compaction": {
    "enabled": false
  }
}

This also disables Pi's automatic overflow recovery. If supercompact is aborted or cannot finish, Pi will not automatically rescue the session. Keep Pi's compaction enabled if you want it as a final fallback.

Preparation and confirmation

The hidden preparation prompt asks the agent to:

• re-read applicable plans, instructions, user-facing documentation, and directly referenced durable sources;
• compare them with actual scoped state and focused verification when applicable;
• correct scoped staleness without broadening the task;
• finish only authorized work that needs no new input;
• surface blockers, questions, approvals, credentials, or decisions;
• verify or persist completed work when applicable and follow scoped rules;
• establish continue or stop and one exact immediate next action.

The confirmation dialog keeps user-supplied preparation context complete while whitespace-normalizing it for display. Agent-created values—the next action and additional summary context—are whitespace-normalized and limited to the first 10 words plus … when longer. Major blocks are separated by one blank line. The complete values remain unchanged in workflow state, the canonical summary prompt, restored context, and continuation metadata.

When confirmation is required, the extension locks it before opening the dialog and rechecks authorization afterward. Configured, prepared-run, or live-session no-confirm permission opens no dialog and begins the same guarded canonical-summary path directly. A confirmed or explicitly authorized stop is a hard constraint. A continue choice is permission, not a mandate: the summary decision may conservatively choose stop when work is complete, blocked, awaiting input, or uncertain.

Canonical summary workflow

After force, accepted confirmation, or an authorized no-confirm request, the extension:

1. Queues a hidden full-context summarization prompt as steering work.
2. Keeps the generated handoff in the transcript as ordinary assistant Markdown.
3. Records a schema-validated continue or stop decision through the internal tool.
4. Runs Pi's native compaction after the summary turn settles.
5. Restores the exact handoff invisibly with authorized preparation metadata.
6. Continues once or waits according to the validated decision.

During the dedicated summary turn, runtime guards block all other tools and reject internal calls outside the required workflow phase. Successful internal control calls are hidden from transcript presentation and terminate the turn without an acknowledgement round trip.

When the decision is recorded, the extension shows the continue-or-wait outcome once as a durable TUI transcript entry. The entry remains available in scrollback instead of disappearing like a transient notification. It is TUI-only session data: it does not enter model context, trigger another turn, or change the provider prompt prefix.

Summary contents

The prompt prioritizes:

• the current objective, direction, authorization boundaries, and actionable state;
• open decisions and blockers;
• verified results separately from mutable observations and reported information;
• completed history compressed to outcomes and material rationale;
• one concrete next action as the final section.

Relevant resources are grouped by work horizon. Exact file paths remain available when files materially affect continuation. The model is instructed not to invent work, broaden scope, include transient identifiers, or treat optional follow-ups as authorized.

Queue, status, and caching

When Pi is idle, preparation and summary messages trigger an immediate steering turn. While Pi is responding, they are queued with steering semantics so the current tool batch finishes first.

Operational status text is shown while the extension is preparing or awaiting confirmation:

• supercompact: preparing 🗜️
• supercompact: awaiting confirmation 🗜️

Explicit live-session permission and an armed one-shot grant add one of these status items:

• supercompact: agent-driven-allow 🗜️
• supercompact: agent-driven-allow-noconfirm 🗜️
• supercompact: agent-driven-allow-noconfirm-once 🗜️

Every status string includes a trailing space after the emoji to separate adjacent status items. Configured permission is intentionally silent in the status area. Consuming or canceling a one-shot grant reveals the prior live-session status. /supercompact agent-driven-deny clears any live-session permission status, while a later /supercompact agent-driven-allow or /supercompact agent-driven-allow-noconfirm displays the new explicit override.

run, agent-driven-allow, agent-driven-allow-noconfirm, agent-driven-allow-noconfirm-once, agent-driven-deny, abort, confirmation, no-confirm execution, summary entry, settlement, and cleanup do not change the extension's active tool vector. This removes extension-caused mid-session schema invalidation and preserves an otherwise reusable prompt-cache prefix.

It does not guarantee provider cache hits. Cache expiration, provider policy, model changes, unrelated extensions, host tool selection, system-prompt changes, and conversation-prefix differences can still cause misses.

Completed or canceled preparation-control messages, stale summary requests, duplicate restored summaries, and completed internal decision artifacts are filtered from later provider context. Substantive preparation work and ordinary conversation remain available.

Headless behavior

• TUI and RPC modes support the final confirmation dialog.
• force works in print and JSON modes because it is explicit authorization.
• run stops before preparation when its effective confirmation mode requires UI; configured or live-session no-confirm mode works headlessly.
• Automatic supercompact works headlessly because it never asks for confirmation.
• agent-driven-allow, agent-driven-allow-noconfirm, agent-driven-allow-noconfirm-once, and agent-driven-deny update or arm session-local permission headlessly.
• Confirmation-required agent execution fails closed without confirmation UI; configured, live-session, prepared-run, and one-shot no-confirm execution work headlessly while retaining every non-dialog guard.
• The bare menu requires TUI or RPC mode.

Failure behavior

The workflow is bounded and leaves the session usable:

• Concurrent preparation, confirmation, and compaction requests receive state-specific guidance.
• Revocation or lifecycle replacement while confirmation is open prevents compaction.
• Invalid decision arguments use Pi's normal correction loop without making the workflow terminal.
• If the model omits decision metadata, the extension requests it again without repeating the summary while the automatic correction budget remains.
• Automatic decision nudges are bounded, but an unsuccessful assistant turn leaves the workflow active for a later retry or resend.
• /supercompact abort cancels extension-controlled work before native compaction; idle use reports an error.
• Aborted, errored, truncated, or unusable summary turns never start manual compaction and do not discard the active workflow.
• Native compaction failure prevents final context restoration, and active native compaction must be canceled through Escape or the host.
• Queueing and compaction failures preserve the specific reason and do not retry automatically; a one-shot grant is retained only when canonical-summary work was never successfully queued.
• Every exit path restores Pi's working message and clears confirmation and decision state without changing tool schemas.
• Native compaction that already completed cannot be rolled back.

Development

npm install --ignore-scripts --workspaces=false
npm run typecheck
npm run test
npm run build
npm run format
npm pack --dry-run

The package is source-loaded by Pi from src/index.ts; no compiled runtime artifact is required.