Status bar and costs
The status bar is implemented by the custom-footer extension (the id is kept for
compatibility). It replaces pi's built-in footer while loaded, and is one renderer with three
layouts.
Layouts
/footer light one compact line
/footer default two lines: identity and context (the default)
/footer heavy adds session totals, cost provenance and every status chip
/footer config open the layout selector
/footer off restore pi's built-in footer (accounting continues)
/footer on show the bar again
/footer status everything the bar drops when it is narrow, in plain text
/footer reload re-read pricing without restarting pi
/footer ascii on|off plain characters instead of symbols (automatic for ISO, ANSI and TTY themes)
/footer todos on|off the todo checklist above the editor
/tips on|off the usage tip under the working line
The layout is stored in <agent dir>/pi-kit/ui.json and survives reloads and new sessions. That
file is shared with the hub, menu and launch-screen settings (hubKey, commandMenu,
pinnedCommands, hiddenCommands, launchScreen, reducedMotion); /footer and /tips change
only their own keys and leave the others intact (tests/status-bar-smoke.ts).
/footer on its own toggles the bar on and off. Any other argument is rejected with the usage
line and changes nothing.
The layouts differ in what they show, not just in line count:
light ● project │ ctx 70% │ on main model
default ● project │ on main │ /path/to/project provider │ model
ctx ████████░░░░ 70% 18k free status chips
heavy (default, then)
session ↑1.0k ↓500 ⟲200 │ cost ? pricing costs.json
extension status chips
What it shows
- Identity: project, model, and the effort tier (
E3 Standard;→ E4while a change waits for your next message). - Boundary and health warnings, which are never dropped to make room for telemetry: unattended mode (shown from what the firewall enforces, never from what the environment claims: a requested-but-not-enforced setting is shown as a misconfiguration), compaction off or degraded, failed or blocked children, and the firewall mode.
- Active work: running children, todo progress, running checks.
- Context: a bar, the percentage and tokens free. Unknown context is shown as
?, never as 0%. - Orientation: git branch, thinking level, profile.
- Telemetry (heavy): session tokens (
↑input,↓output,⟲cache reads) and cost. - Detail: path, provider, session name.
Cost carries its provenance: measured (the provider or catalogue reported it), estimated
(computed from your configured prices), or unknown (?: no price is configured and none was
reported). An unknown cost is unknown, not zero. Usage a partial turn did not report is flagged
partial.
When the terminal is narrow the least important segment goes first (path and provider, then
tokens, then branch and thinking); long segments shorten before anything is dropped. Widths are
measured in terminal columns (wide characters, emoji and escape sequences handled). A render error
falls back to one plain line. /footer status prints every detail the bar dropped and works
without a terminal UI (it writes to standard error).
The bar reads the state other extensions publish (effort, unattended, compaction, running children) from small read-only registries; it never runs a subprocess or reads a file per render.
The working line
While the agent runs, the working line shows the current activity, the elapsed time and the run tokens, for example:
Reading server.ts… (1m 04s · ↑12k ↓~850)
The activity follows the running tool, the stream type (thinking, writing, a tool call), or a
rotating phrase. Output tokens marked ~ are an estimate until the turn records real usage.
The cat
A small ASCII cat shows what the agent is doing, in a fixed width so the text beside it never moves. It uses only printable US-ASCII, so it works over SSH, in a multiplexer and on a basic terminal. While a request runs the cat replaces pi's spinner in front of the working line; between requests it sits in the status bar.
=^o.o^= Thinking… (12s · ↑3.1k ↓~220) a request is running
=^>o>^= Running `npm test`… (31s · ↑3.1k)
=^o?o^= Waiting for input an approval or question is open
=^>w<^= Complete in the bar after a request ends
The face is chosen from the states that are active at once, by a fixed priority rather than by whichever event came last: error, alert, denied, waiting for user, checking, warning, retrying, tool, crunching, thinking, working, streaming, waiting, cancelled, success, idle, then sleeping. What drives each state:
| State | When |
|---|---|
| thinking | a request is running and no output has arrived yet, or the model is streaming thinking |
| streaming | the model is writing its answer |
| working | the model is preparing a tool call |
| tool | a tool is executing |
| waiting for user | a blocking prompt (an approval, a question) is open |
| crunching | the session is being compacted |
| success, warning, denied, error, cancelled | a request ended normally, raised a warning, was refused, stopped on an error, or was aborted |
| denied, warning | a tool returned an error; the text is read, and a refusal by a guard is denied |
A result plays once in the bar and then goes back to the resting face. The resting face does not blink or look around: nothing ticks while the agent is idle, and the only timer the cat ever starts is a short one that clears itself when a result has finished playing.
/footer cat on|off the cat (off restores pi's own spinner)
PI_KIT_CAT=0 turns it off regardless of the saved setting. The cat's animations are a table in
packages/extensions/third_party/custom-footer/cat.ts; a new state is a new row and a place in the
priority list, with no change to the rendering.
Not covered: the two-line "head" cat, a blinking or wandering idle cat, a sleeping state, a
retrying state and an alert state (the faces exist, but nothing in pi reports them to the
extension), and a spinner glyph after the text (pi's indicator sits before it). Tool errors are
classified by their text because no structured denial signal exists, so an unusual refusal message
is shown as a warning.
tests/cat-status-smoke.ts (npm run smoke:cat-status) pins the animation table, the priority,
the wiring to pi's events and the command.
Tips and the todo checklist
A one-line usage tip appears under the working line during a run. It rotates and lists only
commands that are loaded. The checklist above the editor is read from TODO.md (kept by the
todo tool) and shows progress and each item's state. Long items are cut to the terminal's
columns instead of wrapping onto extra rows. The checklist is mounted as a component and re-cut
on every render at the width pi passes, so a terminal resize is handled rather than frozen at the
width seen at mount. An ASCII theme ends the cut with ....
tests/status-bar-smoke.ts pins the component mount and a
narrower render.
Where the tokens went: /usage
trace-ledger records one line per model request in .pi/trace.jsonl: tokens in and out, the
cache read and write split, the cost the provider's price table gave, and the characters of tool
results that request carried, by tool. /usage summarises the current session and any kit children
it started: requests and cost by model and by child, the cache hit rate, the tokens spent on
aborted or failed requests, the tools whose results were largest, and the five largest single
results.
A request with no price in the model table is counted as unpriced, not as free; the report says how many. When a request reads under a quarter of its prompt from cache straight after one that read more than half, the status bar shows a cache warning: the system prompt or tool text changed between turns, or the provider's cache expired. Nothing in the test suite pins that the prefix is byte-stable.
Not covered: /usage reads the last megabyte of the ledger, so a very long session loses its
oldest requests; a child's records are attributed by time window, not by an explicit parent id, so
two sessions sharing one workspace can see each other's children; cost for a provider that reports
no price is not estimated. tests/usage-ledger-smoke.ts pins the recording, the report and the
warning.
Pricing Files
Project pricing is read first:
.pi-kit/costs.json
If that file is missing, Pi checks the user fallback:
~/.pi/agent/pi-kit/costs.json
Example:
{
"inputPerMTok": 0.15,
"outputPerMTok": 0.60,
"cacheReadPerMTok": 0.02,
"cacheWritePerMTok": 0.10
}
Prices are dollars per million tokens. A price you leave out is unknown, not zero: the cost is
shown as estimated only when every token category the session has used has a price. Otherwise
it falls back to the cost the provider reported (measured, when that is above zero), and
otherwise shows ?. For a local model that costs nothing, set the prices to 0 explicitly.
Environment Overrides
$env:PI_KIT_COST_INPUT_PER_MTOK="0.15"
$env:PI_KIT_COST_OUTPUT_PER_MTOK="0.60"
export PI_KIT_COST_INPUT_PER_MTOK=0.15
export PI_KIT_COST_OUTPUT_PER_MTOK=0.60
Optional cache overrides:
PI_KIT_COST_CACHE_READ_PER_MTOK
PI_KIT_COST_CACHE_WRITE_PER_MTOK
A malformed pricing file produces a warning and keeps the previous pricing.
Themes
These themes ship with the full package and the lite surface. Pi discovers a theme,
but only applies it after you select it in /settings or configure theme in
~/.pi/agent/settings.json:
| Theme | Purpose |
|---|---|
gitops-dark |
Existing default kit theme. |
iso-dark |
Standard Linux ISO/ANSI palette and keyboard-only footer glyphs. |
marathon |
ISO/ANSI layout with electric-blue (#5200ff) accents and volt-green (#c2fe0c) highlights. |
high-contrast-dark |
Maximum text and interface contrast. |
colourblind-dark |
Okabe-Ito palette with distinct blue, orange, and yellow states. |
ansi-dark |
Strict 16-colour ANSI palette and keyboard-only footer glyphs. |
tty-dark |
Green-phosphor TTY palette and keyboard-only footer glyphs. |
For iso-dark, ansi-dark, and tty-dark, Luna's footer, todo widget, working line and launch
screen use ASCII keyboard characters such as >, |, =, [x], and ...; they do not emit
box drawing, symbols, or emoji. The working line's tool phrase follows the same automatic
choice and is cut in terminal columns, so a wide glyph at the cut is dropped whole rather than
split. Both read the same theme-name rule. Select a theme either way:
- In Pi, run
/settingsand pick a theme name from the table, or - Add it to
~/.pi/agent/settings.json:
{
"theme": "iso-dark"
}
Without a theme key you get Pi's default (dark/light), even though these themes
are installed. Confirm what is discovered with:
pi list
pi list
Theme credits
The catppuccin-mocha, dracula, gruvbox-dark, monokai, nord-dark, rosepine and
tokyo-night themes use the colour palettes of the projects of those names, re-expressed as pi
theme files; the palettes belong to their respective authors. The marathon and code-marathon*
themes use this project's own palette.