---
status: resolved
parent: "[[057-pi-ui-customization-map]]"
blocked-by: []
resolved-at: "2026-07-31T23:58:11-04:00"
tags:
  - ticket/research
---

# Pi context token data research

## Question

What token and context-window usage data does Pi expose to extensions, footer renderers, session state, or model state, and is there enough structured data to draw a multi-colored context usage bar by token category?

## Findings

Pi exposes a current context-usage API to extensions.
The extensions docs define `ctx.getContextUsage()` and say it returns current context usage for the active model, using last assistant usage when available and estimating tokens for trailing messages.
The implementation returns `{ tokens, contextWindow, percent }` when the model has a positive context window.
After compaction, if there is no valid assistant usage after the compaction boundary, it returns `{ tokens: null, contextWindow, percent: null }` because the context token count is unknown until the next LLM response.
Sources: `docs/extensions.md` section `ctx.getContextUsage()`; `dist/core/agent-session.js` `getContextUsage()`.

Pi's built-in footer already uses the same context-usage data.
The footer calls `this.session.getContextUsage()`, falls back to the active model's `contextWindow` when needed, formats percentage as either a number or `?`, and colors the text as warning above 70% and error above 90%.
It appends an `(auto)` marker when automatic compaction is enabled.
Sources: `dist/modes/interactive/components/footer.js`.

Pi session usage totals have structured categories for `input`, `output`, `cacheRead`, and `cacheWrite`.
The built-in footer iterates all session entries, adds assistant-message usage, tool-result nested usage, branch-summary usage, and compaction usage, then renders usage parts as `↑`, `↓`, `R`, and `W` plus cache-hit rate when cache data exists.
The session export helper likewise exposes totals with `input`, `output`, `cacheRead`, `cacheWrite`, `total`, `cost`, and `contextUsage`.
Sources: `dist/modes/interactive/components/footer.js`; `dist/core/agent-session.js` session stats export logic.

Custom footers can calculate usage totals by iterating `ctx.sessionManager.getBranch()` or broader session entries if available.
The shipped custom footer example sums `m.usage.input`, `m.usage.output`, and `m.usage.cost.total` from assistant messages and notes that token stats come from `ctx.sessionManager` and `ctx.model`.
That example does not include cache read/write or compaction/tool-result usage, but the built-in footer source shows those categories exist in session entries.
Sources: `examples/extensions/custom-footer.ts`; `dist/modes/interactive/components/footer.js`.

The model context-window size is exposed on the active model.
The model docs define `contextWindow` as a model field with a default of `128000`, and custom provider examples register models with `contextWindow` and `maxTokens`.
The built-in footer reads `state.model?.contextWindow`, and `ctx.getContextUsage()` reads `model.contextWindow`.
Sources: `docs/models.md` model field table; `docs/extensions.md` dynamic provider example; `dist/core/agent-session.js`; `dist/modes/interactive/components/footer.js`.

There is not enough public structured data for a true by-content-type context-window bar in version one.
`ctx.getContextUsage()` exposes total tokens, context window, and percent, but not a breakdown by prompt category such as system prompt, user messages, assistant messages, tool results, context files, skills, or summaries.
The session usage categories are billing/usage categories from provider responses and nested calls: input, output, cache read, and cache write.
They are not a decomposition of the current context window contents.
Sources: `docs/extensions.md` `ctx.getContextUsage()`; `dist/core/agent-session.js` `getContextUsage()`; `dist/modes/interactive/components/footer.js` usage aggregation.

A multi-colored bar is still feasible, but the honest v1 categories are limited.
The bar can show total context-window usage from `ctx.getContextUsage()` and, while below a chosen danger threshold, can color segments using available provider usage categories such as input, output, cache read, and cache write.
However, that would visualize cumulative usage totals rather than what is actually occupying the current context window.
If the user specifically wants “what type of tokens are taking up the context window,” the implementation needs either an approximation from session entries or a new Pi API that exposes context-preparation buckets.

## Answer

Pi exposes enough data for a compact context usage bar showing total context-window percentage and threshold coloring.
Pi exposes structured token usage categories for cumulative session accounting.
Pi does not currently expose a public structured breakdown of current context-window occupancy by content type.

The prototype should therefore test two layers:

1. A truthful total context bar using `ctx.getContextUsage()`.
2. Optional segment coloring from available usage categories, clearly treated as usage composition rather than exact context occupancy.

## Limitations

This research used Pi docs and installed package source.
It did not instrument a live extension to inspect all runtime context objects.
The prototype can confirm whether additional useful fields are reachable in practice.

The source code contains an `estimateContextTokens(this.messages)` call, but the public extension API returns only the aggregate estimate.
Without depending on private internals, a customization should not claim exact content-type breakdown.

## Citations

- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`, section `ctx.getContextUsage()`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/models.md`, model field table and provider examples.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-footer.ts`.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/core/agent-session.js`, `getContextUsage()` and session stats export logic.
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/components/footer.js`.
