pi-token-budget
No-summary context-window rollover for Pi with durable notes checkpoints, history recovery, and a checkpoint tool-call fence.
Package details
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
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:
- As the window fills, a reminder asks the model to save a checkpoint and call
new_context. - If the fallback is reached, a checkpoint fence blocks further task tools until the model saves its notes, then requests rollover automatically.
- 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
- Tools and workflow prompts
- Implementation, recovery, and pi-subagents integration
- Validation results
- Releases and migration from 1.x
Development
npm install
npm run typecheck
npm test