# 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.