@giladbarnea/pi-context-auto-heads-up0.0.4
Give Pi agents context-window heads-ups at 50%, 75%, and 90% usage.
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
pi-context-auto-heads-up
Keep the agent aware of its remaining context window.
Long coding sessions can run out of context before the work is done. This Pi extension gives the agent one hidden heads-up when usage crosses 50%, 75%, or 90%.
The agent gets the guidance inside its model context. The user sees only a small notification that names the crossed threshold.
Install
pi install npm:@giladbarnea/pi-context-auto-heads-up
Run /reload in an existing Pi session after installation.
What each heads-up does
| Usage | Guidance |
|---|---|
| 50% | Compare progress with remaining context. Consider delegating noisy read-only work. |
| 75% | Inform the user when substantial work remains. Delegate more implementation work. |
| 90% | Warn the user and other agents. Write a handoff when unattended. Move direct work to fresh agents. |
The wording is intentionally opinionated. It treats delegation and handoffs as context-management tools, not as automatic responses to every large task.
Behavior
- Each threshold fires once per upward crossing.
- A jump across several thresholds emits only the highest crossed threshold.
- Compaction clears pending delivery. A later measured decrease can rearm thresholds; warnings already written are not retracted.
- Mid-run heads-ups are appended persistently after the completed assistant/tool turn. The next natural model call sees them; no extra response is forced.
- In print mode (
pi -p), which outputs only a trailing assistant message, a crossing on the final answer is recorded in the session at once instead, keeping the answer printable. The next prompt delivers that heads-up, including after the process exits, the session resumes, or compaction runs. Other modes deliver it immediately. - Delivery appends new context without rewriting earlier prompt or tool messages. A heads-up remains in history instead of disappearing after one request.
- Resuming a session starts from its current percentage. The extension does not emit retrospective heads-ups.
Timing and compaction
A heads-up records the crossing when the turn finishes, before Pi's next automatic-compaction decision. Compaction may retain an earlier warning, so treat it as a historical crossing—not a guarantee of current usage. The extension does not retroactively remove delivered warnings or invent a percentage while Pi reports usage as unknown.
Persistent delivery avoids a subtle failure of temporary context-hook messages: returning a changed conversation list can fold historical system/tool declarations into a new leading prompt and break preserved-thinking or cache prefixes. See issue #2 for the general failure category, official Pi references and controlled evidence.
Development
npm ci
./setup.sh
npm run check
npm pack --dry-run
See DEVELOPMENT.md for the release process and manual test flow.