Token Metrics

A live throughput meter for the OpenCode TUI. It renders to the right of the session prompt as a VU-style time-series of generation speed, with average, peak, trend, and time-to-first-token.

tok/s ▃▆▇▇█▆▄ 42.0 ▲15% · avg 38.2 · pk 45.0 · ttft 0.8s

What it looks like

The graph grows one column per second as the model streams, scaled to the turn's busiest second:

tok/s ▁ 18.0                                             first token
tok/s ▁▃▅ 33.0 ▲12%                                      ramping up
tok/s ▃▆▇▇█ 45.0 ▲18% · avg 41.2 · pk 45.0 · ttft 0.8s
tok/s ▃▆▇▇█▆▄ - · avg 41.2 · pk 45.0 · ttft 0.8s         tool call — average holds
tok/s ▃▆▇▇█▆▄█▆ 43.0 ▲2% · avg 41.0 · pk 45.0 · ttft 0.8s   resumed
tok/s ▃▆▇▇█▆▄█▆ 43.0 · avg 41.0 · pk 45.0 · ttft 0.8s        holds, scaled to exact tokens
tok/s idle                                               nothing running

The rate and trend are color-coded: red below slowTps, yellow up to fastTps, green at or above it.

• VU meter — one half-block column per second, growing as the turn progresses (no reserved empty space), scaled to the turn's busiest second
• Average — active generation speed: tokens per second over the time actually spent streaming, so tool pauses don't drag it down
• Held frame — when a turn ends the graph, rate, average, peak, and TTFT freeze and stay on screen until the next turn produces tokens
• Exact totals — on completion the graph and peak are rescaled to the provider's reported token count
• Peak hold — the fastest rate observed during the turn, never below the average
• Trend — up/down against the previous second, with percent
• TTFT — time from the assistant message being created to the first streamed token

Install (humans)

One command:

opencode plugin opencode-token-metrics -g

This installs the package from npm and adds it to ~/.config/opencode/tui.json. TUI plugins belong in tui.json, not opencode.json. Restart the TUI afterwards — plugins load at startup and are not hot-reloaded.

The package ships TypeScript source and is transpiled by OpenCode's own runtime, so there is no separate build step.

Manual setup:

// ~/.config/opencode/tui.json
{
  "plugin": ["opencode-token-metrics"]
}

Add options by using the tuple form:

{
  "plugin": [
    ["opencode-token-metrics", { "vuColumns": 20, "vuScale": "fixed", "vuFullTps": 80 }]
  ]
}

Install (for AI agents)

If you are an agent installing this for a user, the full procedure is:

GOAL: install opencode-token-metrics into the user's OpenCode TUI.

1. Run: opencode plugin opencode-token-metrics -g
2. This installs the npm package and adds "opencode-token-metrics" to the
   "plugin" array in ~/.config/opencode/tui.json.
3. If the installer is unavailable, add "opencode-token-metrics" to that
   "plugin" array by hand. Do NOT remove sibling entries. Do NOT add a version suffix.
4. TUI plugins go in tui.json, never opencode.json.
5. Tell the user to restart the TUI. Plugins load at startup; there is no hot reload.
6. Do not touch any other top-level key in tui.json.

Optionally pass options with the tuple form:
["opencode-token-metrics", { "alwaysShow": true }]

Options

Pass options as the second element of the plugin tuple:

{
  "plugin": [
    ["opencode-token-metrics", { "vuColumns": 20, "showTtft": false }]
  ]
}

Option	Default	Description
enabled	true	Disable rendering without uninstalling
rollingWindowMs	5000	Averaging window for the live rate
idleTimeoutMs	1500	Silence after which the rate reads as inactive
minSpanMs	300	Floor on the elapsed span so early samples don't spike
vuColumns	12	Maximum seconds of history shown in the VU meter
vuScale	"auto"	auto scales columns to the turn peak; fixed uses vuFullTps
vuFullTps	50	Full-scale tokens/sec when vuScale is fixed
slowTps	10	Below this is "slow" (red)
fastTps	30	At or above this is "fast" (green)
showVu	true	Show the VU meter
showTrend	true	Show the trend arrow
showAvg	true	Show the turn average
showPeak	true	Show the peak
showTtft	true	Show time to first token
showTokenCount	false	Show the token counter
showElapsed	false	Show elapsed turn time
alwaysShow	false	Keep the meter visible when idle instead of hiding it
idleText	"idle"	Placeholder shown with alwaysShow when there is no data (tok/s idle)
label	"tok/s"	Leading label

How it works

The plugin subscribes to the TUI event bus:

• message.updated — on an assistant message being created, opens a turn and records its start time (for TTFT). On completion, swaps the estimate for the provider's exact tokens.output + tokens.reasoning, freezes the final frame, and keeps it on screen.
• message.part.delta — records streamed text and reasoning chunks and buckets them per second.
• message.part.updated — restarts the live rate when a tool part runs, while keeping the graph continuous across the gap.
• session.deleted — frees that session's meter.

The live rate is tokens in window / elapsed span over the trailing window, measured on the wall clock. The average is turn tokens / active generation time — the time spent streaming, excluding tool pauses. Peak is the highest one-second rate seen during the turn (never below the average); trend compares the last two complete seconds. VU columns auto-scale to the largest bucket in view, scaled to the provider's exact token total when the turn completes.

License

MIT