@graelo/pi-context-usage0.1.0
Claude Code-style /context for pi: see what fills your context window, by category.
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-usage
A pi extension that adds /context: a report of what fills the context window, laid out like
Claude Code's /context.
The report is stored as a session entry that pi shows but never sends to the model, so running
/context costs no context.
Installation
pi install npm:@graelo/pi-context-usage
Usage
/context: the report above./context all: the same report, expanded. It adds one line per tool (costliest first), MCP tool, memory file and skill with its token count, and lists the system prompt's sections with the category each one is counted in.
Categories
Pi builds its system prompt from named sections, each wrapped in a tag of its own name
(<skills>…</skills>, <project_context>…</project_context>, …). It records them, along with
the tool schemas it declares, in the session. Every category below is made of sections, tool
schemas, or the conversation. The section names in this table are what the sections config
key refers to.
| Id | Label | Default color | Contains | Doesn't contain |
|---|---|---|---|---|
system |
System prompt | dim |
Every section no other category claims. With pi 0.99's defaults: preamble, tools, rules, docs, addendum (your appended system prompt) and cwd. The exact set depends on your pi version and extensions; /context all lists it. |
— |
tools |
System tools | muted |
The schemas (name, description, parameters) of the non-MCP tools declared to the model. | The tools section: pi's one-line tool summaries in the prompt count in System prompt. |
mcp |
MCP tools | mdLink |
The mcp_servers section, plus the schemas of MCP tools declared to the model (direct exposure). |
MCP tools exposed through codemode or tool search. The model doesn't see them until it loads them, so they cost nothing up front ("loaded on-demand"). |
memory |
Memory files | error |
The project_context section: context files such as AGENTS.md and CLAUDE.md. |
— |
skills |
Skills | warning |
The skills section: each skill's name, description and file location. Skills marked disable-model-invocation are left out. |
The skill bodies. Once the model reads a skill's file, that text is a tool result and counts in Messages. |
messages |
Messages | accent |
The conversation: your messages, the model's replies and thinking, tool calls and results, compaction summaries. Images count 1200 tokens each, as in pi. | — |
The rest of the window isn't content, so it only takes label and color:
| Id | Label | Default color | Meaning |
|---|---|---|---|
unattributed |
Unattributed | success |
The measured total minus the sum of the category estimates (see below). Hidden when it's zero or less. |
free |
Free space | dim |
What's left: the window minus the total and the buffer. |
buffer |
Autocompact buffer | dim |
pi's compaction.reserveTokens. Auto-compaction triggers once the context reaches the window minus this reserve. Hidden when auto-compaction is off. |
Total, estimates, and Unattributed
The total is pi's own context size, measured from the model's last response. It is the only exact number in the report. Before the first response (or right after a compaction) nothing is measured yet. The total is then the sum of the estimates, and the report marks it "estimated".
Every category is an estimate: chars/4 by default, or your tokenizer.
Unattributed is the gap between the two. It's what a tokenizer approximation can't see:
the model's own vocabulary when it differs from your tokenizer's, and the provider's
formatting around prompt, tools and messages (role markers, special tokens). It shrinks as your
tokenizer gets closer to the model's.
Configuration
Optional. The config lives in config.json under extensions/pi-context-usage/:
- global:
~/.pi/agent/extensions/pi-context-usage/config.json - project (trusted projects only):
<repo>/.pi/extensions/pi-context-usage/config.json
A project file is merged over the global one key by key. Likewise, categories is merged over
the built-in table above, so an entry only needs the keys it changes.
{
"tokenizer": "tik -e o200k_base",
"categories": {
// recolor or relabel a built-in
"unattributed": { "color": 13 },
"memory": { "label": "AGENTS.md", "color": "#d75f87" },
// a new category, claiming sections that would otherwise count as System prompt
"guidance": { "label": "Pi guidance", "sections": ["rules", "docs"], "color": 109, "after": "tools" }
}
}
tokenizer (default ""): a shell command that reads text on stdin and prints its token
count. Empty means chars/4. If the command fails, the report falls back to chars/4 and says
why.
categories: entries keyed by id, either a built-in id from the tables above or a new one.
Each entry takes:
| Key | Meaning |
|---|---|
label |
Name in the legend and section headings. Required for a new category. |
color |
A theme color name (accent, dim, …), a 256-color index (0–255), or a color string (#rrggbb, oklch(…), okhsl(…)). |
sections |
Section names this category claims. Required, non-empty, for a new category. On a built-in it replaces the default list, and [] gives the sections back to System prompt. Not allowed on system, messages, or the rest-of-window ids. A section claimed by two categories is a config error. |
after |
New categories only: the category to place it after, in the grid and the legend. Default: just before Messages. |
An invalid config is reported at session start, and the defaults are used instead.
Development
npm install
npm run check
npm test
pi -e ./src/index.ts
The code is split into three layers, so a change in pi only touches one place:
src/sources/: one module per pi data source. Each returns plain items and does no token math or rendering.src/categories.ts: the built-in category table (the defaultcategoriesconfig) and its resolution. It's the only mapping from pi's concepts to report categories.src/aggregate.tsbuilds the snapshot, andsrc/report/renders it.
License
MIT