pi-autocompacter0.1.0

Pi Autocompacter

Autocompacter adds agent-led context checkpoints to Pi. It works at turn boundaries. It preserves the active task in a summary and resumes unfinished work.

Requirements

• Pi 1.4.x
• Node.js 24 or newer for development and tests

Install

Install the published package globally for your Pi agent and child processes:

pi install npm:pi-autocompacter

For a source checkout, run pi install "$PWD" from the package directory instead.

Restart Pi or run /reload. The package installs the extension and the autocompacter skill.

For a local project install, use pi install -l "$PWD". Trust the project when Pi asks. Review the source before you trust it.

To test the extension without installation, run:

pi --extension ./src/index.ts --skill ./skills/autocompacter

Use

The agent can call self-compact. The tool accepts an optional handoff note. The note should contain the task state, key paths, constraints, and next action.

The extension queues the checkpoint. It waits for the current turn and all its tool results. It then uses Pi's summary generator and active model. Work continues after a requested checkpoint.

Command	Action
/autocompacter	Compact now. If Pi is busy, queue the checkpoint.
/autocompacter Preserve the release checklist	Add a user focus to a manual checkpoint.
/autocompacter status	Show token use, active limits, settings path, and errors.
/autocompacter-config	Open the setup wizard.
/autocompacter-config set 200k, 225k, 235k	Set notice, warning, and force limits without the wizard.
/autocompacter-config reset	Restore the default limits.

The wizard accepts counts such as 200000, 200k, 0.2m, and two hundred thousand.

Context levels

The terminal status bar fills as token use grows. Colored vertical marks show the three levels.

Level	Default	Behavior
Notice	200k	Ask the agent to prepare a checkpoint.
Warning	225k	Ask the agent to compact after the current safe step.
Force	235k	Compact automatically at the turn boundary.

The force limit cannot exceed 270k. Notice must be below warning. Warning must be below force.

For a smaller model window, the extension lowers all three limits. It keeps 20% of the window free for the response and summary work. Use /autocompacter status to see the active limits.

The extension saves project settings in .pi/autocompacter.json. Example:

{
  "notice": 200000,
  "warning": 225000,
  "force": 235000
}

An invalid settings file pauses automatic compaction. Manual checkpoints remain available. Run /autocompacter-config to replace the file.

Child Pi processes

Each child Pi process must load the extension. A personal package installation normally provides it to child processes. A --extension flag applies only to that invocation. Pass the extension path to each child that uses explicit flags.

The skill gives usage instructions. It does not register the tool by itself.

Failure behavior

A failed summary does not replace the original context. The extension uses a short retry delay at later turn boundaries. It pauses automatic attempts after three failures. Run /autocompacter to retry.

Develop

Run these commands from a source checkout:

npm install
npm run check

Tests cover parsing, configuration, threshold scaling, UI state, turn lifecycle, failures, and continuation.

Live smoke test

Use a source checkout and a low-cost model with tool support. This example uses OpenAI:

OPENAI_API_KEY=... npm run smoke:live

The default model is openai/gpt-4.1-mini. To select another model:

AUTOCOMPACTER_MODEL=openrouter/openai/gpt-4.1-mini \
OPENROUTER_API_KEY=... \
npm run smoke:live

The script checks the tool call, the autocompacter checkpoint, and the reply after compaction. It keeps Pi state in .cache/smoke-live. Provider charges and network access apply.

See behavior details and verification results.