Precedence per key: env, trusted project .pi/settings.json, user ~/.pi/agent/settings.json, default.
Project and user context-size objects deep-merge, so a project may override one key only.
Project settings are ignored while the project is untrusted.
Settings files take JSON numbers only; env values take numeric strings.
Both keys resolve once per session_start.
An invalid value never falls through to a lower-priority source.
Instead, a wrong type, an out-of-range value, a non-numeric env value, or warningPercent not below errorPercent shows one warning naming the problem, and both thresholds fall back to 70 and 85.
Hooks/events:
session_start
agent_start
turn_end
agent_end
model_select
session_compact
session_shutdown
Emits:
footer:segment to publish or clear the context-size footer segment.
Behavior
Shows current context-window usage as a 10-cell bar.
If @bugabinga/pi-ext-footer is loaded, publishes a context-size footer
segment in the llm zone with order 1.
Otherwise uses Pi status text with id context-size.
The footer segment is the bar alone.
Its length encodes the percentage and its color encodes the pressure, so
percent and token counts would only repeat it.
Usage color:
below warningPercent (default 70%): muted
≥ warningPercent: warning
≥ errorPercent (default 85%): error
unknown percent: muted
The bar uses dim when the text color is muted.
Otherwise it uses the same color as the text.
Outside TUI mode the bar is replaced by plain status text such as
context 26% used, 738k left, because other clients render the status line as
text in an unknown font.
Token counts there use k and M units.
No UI update runs when UI is unavailable.
Clears footer/status when context usage is unavailable.
Clears status on session shutdown.
Debug
Opt in through debug logging.
Safe events: session.start, session.shutdown, and update with UI/render outcome classification.
# context-size
Context-window usage telemetry for Pi.
## Install / load
Loaded through the root `pi-ext` package.
See [root README](../../README.md).
## Commands / tools / settings
Commands:
none.
Tools:
none.
Settings:
| Key | Env | Default | Valid range |
| --- | --- | --- | --- |
| `context-size.warningPercent` | `PI_CONTEXT_SIZE_WARNING_PERCENT` | `70` | number `> 0` and `≤ 100`, below `errorPercent` |
| `context-size.errorPercent` | `PI_CONTEXT_SIZE_ERROR_PERCENT` | `85` | number `> 0` and `≤ 100`, above `warningPercent` |
Example `settings.json`:
```json
{ "context-size": { "warningPercent": 60, "errorPercent": 80 } }
```
Precedence per key: env, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project and user `context-size` objects deep-merge, so a project may override one key only.
Project settings are ignored while the project is untrusted.
Settings files take JSON numbers only; env values take numeric strings.
Both keys resolve once per `session_start`.
An invalid value never falls through to a lower-priority source.
Instead, a wrong type, an out-of-range value, a non-numeric env value, or `warningPercent` not below `errorPercent` shows one warning naming the problem, and both thresholds fall back to `70` and `85`.
Hooks/events:
- `session_start`
- `agent_start`
- `turn_end`
- `agent_end`
- `model_select`
- `session_compact`
- `session_shutdown`
Emits:
- `footer:segment` to publish or clear the `context-size` footer segment.
## Behavior
Shows current context-window usage as a 10-cell bar.
If `@bugabinga/pi-ext-footer` is loaded, publishes a `context-size` footer
segment in the `llm` zone with order `1`.
Otherwise uses Pi status text with id `context-size`.
The footer segment is the bar alone.
Its length encodes the percentage and its color encodes the pressure, so
percent and token counts would only repeat it.
Usage color:
- below `warningPercent` (default `70%`): muted
- `≥ warningPercent`: warning
- `≥ errorPercent` (default `85%`): error
- unknown percent: muted
The bar uses `dim` when the text color is muted.
Otherwise it uses the same color as the text.
Outside TUI mode the bar is replaced by plain status text such as
`context 26% used, 738k left`, because other clients render the status line as
text in an unknown font.
Token counts there use `k` and `M` units.
No UI update runs when UI is unavailable.
Clears footer/status when context usage is unavailable.
Clears status on session shutdown.
## Debug
Opt in through [debug logging](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, and `update` with UI/render outcome classification.