pi-token-budget

No-summary context-window rollover for Pi with durable notes checkpoints, history recovery, and a checkpoint tool-call fence.

Packages

Package details

extension

Install pi-token-budget from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-token-budget
Package
pi-token-budget
Version
2.0.3
Published
Nov 20, 2026
Downloads
749/mo · 51/wk
Author
7resp4ss
License
MIT
Types
extension
Size
253.4 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-token-budget

npm version license

No-summary context rollover for Pi, inspired by Codex's token_budget workflow (#27488).

The model saves its progress in durable notes, starts a fresh context window, and retrieves past details from read-only history. This replaces Pi's summary-based compaction while keeping the task's working state under the model's control.

Install

pi install npm:pi-token-budget

Or try it without installing:

pi -e npm:pi-token-budget

Requires Pi Packages and extension tool_call hooks. No build step is needed.

Usage

The extension manages context rollover automatically:

  1. As the window fills, a reminder asks the model to save a checkpoint and call new_context.
  2. If the fallback is reached, a checkpoint fence blocks further task tools until the model saves its notes, then requests rollover automatically.
  3. In the fresh window, the model reads its checkpoint and recovers missing details from history.

Use Pi's /compact command to request a checkpoint and a fresh window manually. Press Esc to cancel. Rollover leaves the filesystem and environment intact.

During ordinary work, the model decides when to take notes. Rollover happens at an eligible Pi boundary; an actual context overflow uses the latest available checkpoint and history.

Configuration

Defaults work out of the box. To request rollover at a specific used-token threshold, set tokenBudget in ~/.pi/agent/settings.json:

{
  "tokenBudget": {
    "hardRolloverUsedTokens": 256000
  }
}

The hard trigger is disabled by default (0). Set PI_TOKEN_BUDGET_DISABLED=1 to disable the extension. All settings and per-model overrides are described in src/config.ts.

Documentation

Development

npm install
npm run typecheck
npm test

License

MIT