statusline

English | 中文

npm · pi packages gallery · repository

Replaces pi's footer with a labelled two-row one. Every value carries a word, so nothing has to be decoded from a symbol or remembered from a legend.

Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M                   Input 194k  ·  Output 89k  ·  Cache hit 99.9%  ·  Cost $0.229
~/.pi (master)                                                               deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
LSP Active: typescript

A narrower terminal gives the row up in a fixed order rather than all at once: the 471k / 1.0M detail goes first, then the input/output volumes, leaving the hit rate and the bill. Below about 60 columns only the meter is left. Every step is a whole value — a number is never shown cut in half.

What each part is

Part	Meaning
Context + meter + 47.1%	Share of the model's context window in use. The fill turns warning above 70% and error above 90%, the same thresholds pi's shipped footer uses, and the percentage changes color with it
471k / 1.0M	Absolute context tokens over the window size. The first thing dropped when the terminal is narrow
Input / Output	Session prompt and completion tokens. Input counts the prompt tokens that were neither read from nor written to cache, because pi reports those two separately in the same usage object
Cache hit	The latest turn's cache hit rate, cacheRead / (input + cacheRead + cacheWrite)
Cost	Session cost, in USD unless a config file names another currency (see below)
Effort	The active thinking level
TTFT	Time from request dispatch to the first streamed token
tok/s	Decode throughput, i.e. output tokens per second of decode time
Last line	Other extensions' ctx.ui.setStatus() entries, so they do not silently disappear

The meter

The meter is a fixed 20 cells and never stretches to the terminal. That is the one structural rule taken from cli-progress's shades_classic preset (≈10M downloads/week): its bar has a fixed barsize and is never widened to fill the row. An earlier revision here did stretch it, which made the meter read as chrome rather than as an instrument.

The glyphs are that preset's block fill and shaded block track, with a 1/8-cell leading edge (▏▎▍▌▋▊▉) so the fill grows smoothly instead of jumping a whole cell at a time.

Configuration lives at the top of render.ts:

Constant	Default	Notes
BAR_CELLS	20	Meter width. Narrower for a quieter footer, wider for more resolution
BAR_FILL	█	Fill glyph
BAR_TRACK	░	Set to "" for a trackless meter, or "─" for a hairline one
QUIET_STATUS	pi-lens	[statusKey, pattern] pairs whose matching text is hidden as "nothing to report"

Currency

pi prices every model in USD and its cost field carries no unit at all, so the footer cannot know what you were actually billed. What a session cost in RMB is set by whoever sold you the credit, not by a market feed, which is why the rate is configured rather than fetched.

Create ~/.pi/agent/statusline.json:

{
  "currency": {
    "code": "CNY",
    "perUsd": 7.12
  }
}

• code picks the symbol (CNY and RMB give ¥; the table also knows USD, EUR, GBP, JPY, HKD, TWD, SGD, KRW and INR). A code the table does not know is printed as it is.
• symbol overrides the table, for a currency it does not list or a different separator.
• perUsd is how many units of that currency one dollar buys — the rate you were actually charged. It has to be a positive number; anything else is refused and the footer stays in USD.

With the file above, the same session reads Cost ¥1.63 instead of Cost $0.229. The file is read once per session, so edit it and /reload. A file that is there but unusable says so in a notification, rather than silently showing dollars with nothing to explain why.

Metrics

Throughput and latency follow the deepseek-harness turn-metrics contract (packages/client/ui-chat/src/client/contract/turn-metrics.ts), including its number formatting:

ttftMs   = firstTokenTime - stepStartTime
decodeMs = completedTime  - firstTokenTime
tok/s    = usage.output / (decodeMs / 1000)

So the rate excludes prefill and time-to-first-token, which is the industry-standard "output tokens per second" figure.

• Final values are exact. They use the provider's reported usage.output over the measured decode window.
• Live values are estimates, marked with ~. Providers report usage only on the final stream chunk, so the streaming token count is inferred from streamed characters scaled by a tokens-per-character ratio learned from this session's own reported usage.
• TTFT is exact as soon as the first token arrives and never changes for that turn.
• The reading appears after the first turn completes in the session, because it can only come from streamed events.

Requirements and limits

• One extension owns the footer. ctx.ui.setFooter() is exclusive, so installing another footer extension alongside this one is a race, not a merge. This extension stands down if pi-fancy-footer announces itself, so the two coexist without fighting.
• The footer renders on ctx.sessionManager.getEntries() and ctx.getContextUsage(), both public API; nothing reaches into pi's internals.
• Provider status such as MCP: 2 servers enabled is informational and can be turned off at its source: settings.mcpFooterStatus in ~/.pi/agent/mcp.json. LSP Inactive from pi-lens has no such setting, so it is filtered here as a "quiet" status.

Install

# on its own
pi install npm:@reedchan/statusline

# or as part of the collection, which installs every extension in the repository
pi install npm:useful-pi-extensions

Then /reload.