@taimoorchatha/pi-context-footer

A pi coding-agent extension. Replaces pi's footer with a turn-by-turn context-usage readout:

████░░░░░░ 42.3% 84k/200k +1.2k  assistant: response (320 out)
^bar        ^pct  ^tokens ^delta  ^last event

• Updates after every user message, assistant message, and tool call.
• Bar color: green → yellow at 65% → red at 85%.
• Real token counts come from the provider (ctx.getContextUsage()) after each assistant turn. Between turns, deltas are ~4-chars-per-token estimates reconciled against the real value on the next assistant reply. Estimated rows are marked with a leading ~.
• Default shows only the most recent event. /context-footer <N> expands to the last N turns on separate lines (capped at 20).

Install

pi install npm:@taimoorchatha/pi-context-footer

Or drop the source file directly into ~/.pi/agent/extensions/ (global) or .pi/extensions/ in a project:

curl -o ~/.pi/agent/extensions/context-footer.ts \
  https://raw.githubusercontent.com/taimoorchatha/pi-extensions/main/packages/context-footer/src/index.ts

No compilation — pi loads TS directly via jiti. /reload or start a new session and it activates.

Commands

/context-footer           toggle on/off
/context-footer <N>       show last N turns on separate lines (0 = hide, max 20)
/context-footer on | off  explicit

What counts against the context window?

Everything sent to the LLM per turn:

1. System prompt — pi's baseline instructions + tool descriptions + any AGENTS.md + loaded skills. Usually 5–15k tokens on its own before the conversation starts.
2. Tool results — read on large files, bash output on builds/tests/logs. Usually the dominant contributor in coding sessions.
3. Assistant responses — including the hidden reasoning tokens on thinking-capable models.
4. Tool calls — the arguments the model sent.
5. Your prompts — typically the smallest slice.

That's why the bar can jump 5–10% after a single large file read while a short typed prompt barely moves the needle. The delta column reflects all of it.

Design notes

Learned from rebuilding this after an earlier attempt crashed pi hard:

• No pi.sendMessage() calls, ever. The old design injected a "marker" message after each turn and tried to hide those markers from the LLM with an on("context") filter. The filter checked the wrong field, so every marker leaked into the model's view of the conversation, looking like a new short user turn — the model kept replying briefly and its own reply triggered another marker, producing a tight reply loop. This extension is pure footer. It never touches the LLM's message list.
• Only documented ThemeColor keys. theme.fg() throws on unknown keys, and because it's called from inside the TUI's render loop the throw can kill pi outright (terminal stays stuck in alt-screen + raw mode). Uses only text, accent, muted, dim, success, warning, error.
• Defensive try/catch in every lifecycle handler and inside the footer's render(). If anything unexpected throws, the footer silently degrades to ctx ? instead of taking pi down.

License

MIT — see LICENSE.