@sven1103-agent/pi-metrics0.1.1

pi-metrics

Live LLM latency HUD for the Pi coding agent: time to first token, inter-token latency and decode throughput — per call and per session. No network calls, no telemetry, no runtime dependencies.

The same session in graphStyle: "block":

The animations are generated by scripts/demo.mjs, which drives the real renderer over a virtual clock. They play at real time — one second of animation is one second of decoding — so the cadence you see is the cadence the HUD actually has. The figures are illustrative: they exercise the states and the colour ramp the HUD can show, and are not a benchmark. Regenerate with scripts/record-demo.sh.

Contents

• Install
• What the HUD shows
• Commands
• Settings
• What it measures
• Supported Pi versions
• What it does not do
• Maintained by

Install

pi install npm:@sven1103-agent/pi-metrics

Or pin a release from git:

pi install git:github.com/sven1103-agent/pi-metrics@v0.1.1

What the HUD shows

 ─ pi-metrics · demo-model ─────────────────────────────────────────────────────────────── 3 calls ─
 ○ waiting  ● writing  ‖ paused  ✔ done  [██████░░░░░░]  14.9 tok/s  (est)  30 tok  waiting 900ms

 TPS tok/s  ·  fast 100  ·  avg 32  ·  p95 79                                  20s  ·  max 100 auto

                                                                     ⢸⣿⣿⣿⣿⡇
                                                                     ⢸⣿⣿⣿⣿⡇    ⢀⣀⣀⣀⣀
 ⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⠒⢸⣿⣿⣿⣿⡇⠒⠒⠒⠒⣼⣿⣿⣿⣿⣦⣤⣤⣤⣤⣄⣀⣀⣀⣀⠒⠒⠒⠒⠒
 ⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⢸⣿⣿⣿⣿⣷⣶⣶⣶⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆⣀⣀⣀⣀
 ───────────────────────────────────────────────────────────────────────────────────────────────────
 TTFT ms  med 400ms  max 500ms                    │ ITL ms  med 22ms  max 38ms
 ⡇⡀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ │  ⡇
 ⣧⡇                                               │ ⢠⡇⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤
 ⣿⡇                                               │ ⣼⡇
 ⣿⡇⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂ │ ⣿⡇⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂⠂
 ───────────────────────────────────────────────────────────────────────────────────────────────────
 STATS  med conn/pre 100ms/300ms  med first 400ms  med ITL 22ms  p95 ITL 38ms  3 calls

The panel sits above the editor by default. From the top:

• Header — the model name and the number of calls recorded this session.
• State row — the live state, a pressure bar, throughput, and provenance.
• TPS chart — session throughput over time.
• HIST charts — TTFT and ITL, one column per call.
• STATS row — session medians and the call count.

style: "compact" collapses the TPS and HIST charts to one line each, instead of the tall multi-row graphs.

The state row

All four states are drawn on every frame with the active one highlighted, so there is nothing to re-read mid-response:

The rest of the row, left to right:

The TPS and HIST charts

The TPS chart is a session timeline, one column per completed writing second, height = tokens generated that second. It is never reset per call, so separate writing actions stay comparable. The title's left side is measurement (avg, p95); its right side is the chart's own axes — the recording window in seconds, then the tok/s ceiling, marked auto when derived from the session.

The HIST charts plot TTFT and ITL one column per call. In style: "normal" they sit side by side, with the session median drawn as a reference line and the median and max in the title; in compact, each gets a one-line sparkline beside its median.

Commands

Display commands take effect immediately and last until Pi exits. Each one prints the settings.json line that makes the change permanent — the extension cannot write that file itself, because Pi's extension API exposes no settings-write call, and editing the file underneath Pi's settings manager risks dropping unrelated keys.

Settings

All optional, under the pi-metrics key in ~/.pi/agent/settings.json:

{
  "pi-metrics": {
    "enabled": true,
    "placement": "aboveEditor",
    "style": "normal",
    "graphStyle": "braille",
    "colorMode": "calm",
    "timeline": true,
    "liveTimeline": true,
    "history": 120,
    "tpsWindow": 120,
    "tpsMax": "auto",
    "tpsGood": 30,
    "tpsBad": 15,
    "tpsFast": 100,
    "charsPerToken": "auto",
    "cost": true,
    "persist": false
  }
}

placement accepts aboveEditor / belowEditor and, because a natural guess is otherwise silently ignored, also above / below. A value that is unusable in any other way is reported at startup as a warning and replaced by the default, so a typo cannot degrade the HUD quietly.

The pre-0.1.0 names rateWindow / rateMax / rateGood / rateBad / rateFast are still read as aliases, so an existing config keeps working. When both a legacy and a new key are set, the new key wins.

What it measures

A few properties are worth stating explicitly, because the figures can mislead without them:

• conn / prefill — /metrics report splits TTFT into conn (request → response headers) and prefill (headers → first token) when the provider exposes the boundary. They are two separate medians, and medians are not additive, so they need not sum to the med first beside them. conn folds in server-side queueing, so the split compares calls to the same provider rather than across providers.
• (usage) vs (est) — throughput is tagged with its source: (usage) when the provider reported usage.output (the call is finished and its TPS buckets were rescaled to the exact count), (est) in amber while the figure still comes from streamed characters. Estimates are never shown as if they were measured.
• Latency is the median; throughput is the mean. Latency has a long right tail (cold connections, provider queueing) where single outliers drag a mean away from the typical call. Throughput has no such noise: a stalled second is delivered throughput, and a median would flatter it.
• Colour is relative, not absolute. One cool-to-hot hue ramp carries severity as the ratio to the session's own typical value, so the same palette means the same thing on an 8 tok/s local model and a 200 tok/s hosted one. A third of typical is the cool end, typical is the middle, three times typical is the warm end. In the charts the ramp is applied vertically: a bar's top edge carries the colour of its own value and the fill fades toward the axis baseline below. colorMode picks how loud it is: calm keeps the theme's own colours, vivid uses saturated anchors, mono drops hue entirely.
• TTOUT is not on the HUD panel. It appears in /metrics report, in the persisted card, and in the one-line status shown when the HUD is toggled off — alongside the per-call cost.

Supported Pi versions

Each version is its own CI job, so the Checks tab names the exact release that broke:

Below 1.1.0 the published typings are incomplete: the extension loads, but does not typecheck. That lane asserts the load gate and only reports the error count as evidence for the floor — it never requires errors to be present, so an upstream backport lowers the floor without breaking the build. The @earendil-works/pi-ai peer floor matches at >=1.1.0; the other two stay at * as Pi requires.

Interactive rendering is verified manually. The widget is TUI-only, so a headless run cannot exercise it. Do not read these badges as covering what the HUD looks like.

What it does not do

• It does not send anything anywhere. No network calls, no telemetry, no credential access. See SECURITY.md for the full scope, written against the source, and for how to report a problem privately.
• It installs nothing. package.json declares no runtime dependencies, so adding this package adds no code for you to audit — npm audit has no tree to report on for it.
• It does not show a session cost. Pi's footer already carries that total; this extension only adds a per-call cost column to /metrics report and the persisted card.
• It does not measure prompt tokens per second; it measures decode throughput.
• It does not persist history across sessions unless persist is enabled.

Maintained by

Sven Fillinger, Research Software Engineer, University of Tübingen, through my agent alias @sven1103-agent — the account that authors the commits here. Same person; the alias exists so the automation is labelled as automation.

The npm package is published from an npm account of the same name, for the same reason: npm view @sven1103-agent/pi-metrics maintainers names the agent account, not a human one, so the automation is visible in the registry too rather than being fronted. I own that account and its recovery factors, so it stays accountable to a person.

License

MIT