pi-tps-status

Shows a live tokens-per-second (TPS) widget in the pi-coding-agent status bar while the agent streams a response. Display mode, counting strategy, colors, and end-of-stream behavior are configurable.

What you get

• Live TPS meter: a sliding-window rate updated on every streamed chunk, color-coded by speed tier (⚡ TPS: 42.1 tok/s [provider]).
• TTFT and stats modes: the status suffix can show time-to-first-token, total tokens / elapsed time, both, or neither.
• Three counting strategies: estimate (chars ÷ 4), direct (one token per chunk), or provider (exact usage reported by the provider, back-dated across the stream window).
• Provider reconciliation: when the provider reports final usage, the meter merges it with fallback estimates, so the displayed total matches the provider's number, not a guess.
• Tool time excluded: while the agent runs a tool, the clock is paused, so the rate reflects pure generation, not tool execution.
• /tps command: an interactive settings list (display mode, counting strategy, end-of-stream behavior) persisted to config.json with atomic writes and validation.

Quick start

The widget appears automatically on session start:

⚡ TPS: 42.1 tok/s [provider]

Run /tps to configure it:

/tps

Installation

pi install npm:pi-tps-status

From a local checkout:

pi install /path/to/pi-tps-status

Display modes

Mode	Status bar shows
tps	⚡ TPS: 42.1 tok/s [provider]
ttft	TPS plus (TTFT: 812 ms)
stats	TPS plus (1234 tok in 12.3s)
full	TPS plus (1234 tok in 12.3s · TTFT: 812 ms)

The source tag after the rate is [provider] (exact usage), [est] (chars ÷ 4), or [chunk] (per-chunk counting).

Speed tiers

The rate is colored by four configurable thresholds (defaults: slow 0, medium 15, fast 30, blazing 45 tok/s):

Tier	Default color
slow	#ff4444
medium	#ffaa00
fast	#00ff88
blazing	#44ddff

Counting strategies

Strategy	How tokens are counted
estimate	ceil(chars / 4) per streamed delta; CJK characters count as one token each.
direct	One token per streamed chunk.
provider (default)	Only the provider's reported usage counts; the widget shows -- until the provider reports.

useProviderTokens (default on) prefers the provider's exact counts whenever they are reported, regardless of strategy. Final provider usage is back-dated across the stream window so the rate curve stays smooth instead of jumping at the end.

End-of-stream behavior

Behavior	After streaming stops
average	The widget shows the average rate over the whole generation.
last	The widget keeps the last live (sliding-window) rate.

Settings

Settings live in ~/.config/pi-tps-status/config.json, created automatically when a setting is changed. On non-Windows platforms, the config directory honors XDG_CONFIG_HOME when set (falling back to ~/.config); on Windows it always uses ~/.config:

{
  "display": "tps",
  "tpsSlow": 0,
  "tpsMedium": 15,
  "tpsFast": 30,
  "tpsBlazing": 45,
  "colorSlow": "#ff4444",
  "colorMedium": "#ffaa00",
  "colorFast": "#00ff88",
  "colorBlazing": "#44ddff",
  "slidingWindow": 1000,
  "useProviderTokens": true,
  "countStrategy": "provider",
  "endTpsBehavior": "average"
}

Setting	Range / values	Default
display	tps | ttft | stats | full	tps
tpsSlow / tpsMedium / tpsFast / tpsBlazing	0-1,000,000, strictly ascending	0 / 15 / 30 / 45
colorSlow … colorBlazing	#rrggbb	see above
slidingWindow	100-30,000 ms	1000
useProviderTokens	true | false	true
countStrategy	provider | estimate | direct	provider
endTpsBehavior	average | last	average

Writes are atomic (a UUID-named temp file with 0600 permissions, fsynced and renamed over the target, with stale temp files swept on the next write), and invalid values are rejected with a warning notification that names the offending key and the fallback used.

How the meter works

• Sliding window: token samples are kept for the configured window; the rate is the token delta over the sample span (minimum 250 ms before a rate is shown).
• Pause/resume: tool executions increment a counter; while it is non-zero the clock is paused, so tool time never dilutes the rate.
• Reconciliation: at the end of a turn the provider's final token count replaces the estimate when provider counting is enabled (useProviderTokens or countStrategy: provider), with any fallback-counted tokens the provider didn't cover added on top.
• TTFT: measured from the user message to the first streamed delta (text, thinking or tool call).

Troubleshooting

• The widget shows --. No stream has started yet, or the stream was shorter than the 250 ms minimum span. Send a message and watch it stream.
• The rate looks wrong. Check the counting strategy: estimate and direct are approximations; provider (or useProviderTokens: true) uses the provider's exact numbers.
• Settings were rejected. The notification lists the invalid keys and the defaults applied. Fix the values in config.json or re-run /tps.
• Settings moved. Older versions stored settings under the tokenSpeed key in ~/.pi/agent/settings.json; they now live in ~/.config/pi-tps-status/config.json and are not migrated automatically.

Development

Requires Node.js ≥ 22.19 and npm.

npm install
npm test
npm run typecheck

Credits

• Gabriel Sanhueza, pi-token-speed, this extension is derived from it
• Anthony Fangqing, pi-tps, the pi port of the original TPS meter on which pi-token-speed builds
• Tarquinen, oc-tps, the original TPS extension this family traces back to
• badlogic, pi-coding-agent and the TUI status-bar APIs

License

MIT