# Pi Preemptive Compact

An ultra-light [Pi](https://github.com/earendil-works/pi-mono) extension that compacts context earlier, at a fixed token threshold you control.

After a successful compaction, it sends a hidden continuation message so the agent can resume the current task from Pi's summary.

## Why compact earlier?

More context isn't always more useful. Old tool output, stale decisions, and abandoned paths can make the current task harder to follow. Compacting earlier may give an agent a smaller working set and help it stay focused.

The trade-off depends on the model and the task: compaction can also remove details that still matter. Treat the threshold as a value to tune, not a universal optimum.

## Install

From npm:

```bash
pi install npm:pi-preemptive-compact
```

Or directly from GitHub:

```bash
pi install git:github.com/SannaMarcoDev/pi-preemptive-compact
```

Restart Pi after installation.

## Configuration

The threshold is a source-level setting. Change this exported constant in `preemptive-compact.ts`:

```ts
export const COMPACT_THRESHOLD_TOKENS = 150_000;
```

The default is 150,000 tokens. Lower values compact sooner; higher values keep more context.

## Behavior

On each `turn_end`, the extension reads Pi's current context usage. At or above the configured threshold, it:

1. starts one compaction;
2. ignores further turn-end events while that compaction is running;
3. sends a hidden message with `triggerTurn: true` after success, which resumes the task from the summary.

If usage data is unavailable, it does nothing. If compaction fails, it clears its lock so a later turn can try again.

## Pi's native compaction

Pi's built-in compaction remains active when enabled. It uses the context window and `reserveTokens` to compact near the model limit; this extension adds an earlier fixed threshold.

Keep native compaction enabled as a fallback if the extension hasn't run or an early compaction attempt fails:

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

Put these settings in `~/.pi/agent/settings.json` and adjust them for your setup.

## Test

```bash
npm test
```

The test covers the threshold trigger and the hidden continuation sent after a successful compaction.

## License

MIT. See [LICENSE](LICENSE).