OpenCode TPS Plugin

Real-time token speed metrics — PP and TG speeds with session totals — displayed in the OpenCode sidebar.

A TUI plugin for OpenCode that monitors Prompt Processing (PP) and Token Generation (TG) speeds during every LLM interaction. Accumulates session-wide token totals including cache and reasoning tokens. Handles subagent nesting, connection drops, and rapid reconnects.

Features

• PP speed — input tokens per second (authoritative from step-finish)
• TG speed — output tokens per second, live (cur) during streaming and (avg) after completion
• Session totals — cumulative input, output, cache, and reasoning tokens across all messages
• Subagent nesting — multi-layer subagent tokens accumulate without corrupting main thread speeds
• Chaos-resilient — survives connection timeouts, rapid reconnects, stale events, and interleaved failure modes
• Configurable — toggle each metric on/off and adjust the refresh interval via JSON config
• Dual fallback chain — message.updated + session.status idle catch missed step-finish events
• No build step — loaded directly by OpenCode at runtime as raw .tsx

Tech Stack

| Component | Technology | Version | |-----------|-----------|---------| | Language | TypeScript | ^5.4.0 | | UI Framework | SolidJS (via @opentui/solid) | runtime | | Plugin API | @opencode-ai/plugin/tui | runtime | | Test Runner | Vitest | ^1.6.0 | | Runtime | Node.js | >= 18 | | Module System | ESM (type: "module") | — |

Architecture

Three-layer design with strict separation of concerns:

┌─────────────────────────────────────────────┐
│  UI Layer (SolidJS JSX)                     │
│  - Registers in sidebar_content slot        │
│  - Reads tracker.state() via reactive sigs  │
│  - Uses api.theme.current for colors        │
├─────────────────────────────────────────────┤
│  Tracker (createTracker)                    │
│  - SolidJS signals for state                │
│  - accumulateTokens() for subagent routing  │
│  - Guards: double-start, double-end,        │
│    negative deltas, not-generating          │
│  - Live TG speed ticker via setInterval     │
├─────────────────────────────────────────────┤
│  Event Handlers (tui function)              │
│  - message.part.updated → step-start/finish │
│  - message.part.delta → text deltas         │
│  - session.status → busy/idle fallback      │
│  - message.updated → final tokens fallback  │
│  - Message-ID correlation for subagent      │
│    detection + stale event rejection        │
└─────────────────────────────────────────────┘

Data Flow

1. step-start → startGeneration() — starts timer, marks prefill phase
2. First text delta → onFirstToken() — records first-token timestamp, ends prefill
3. Each delta → addDeltaChars() — accumulates live character count
4. step-finish (matching messageID) → endGeneration() — computes PP/TG speeds, accumulates session totals
5. step-finish (subagent, different messageID) → accumulateTokens() — adds to session totals without affecting speeds or generation state
6. Fallbacks — message.updated (authoritative tokens) or session.status idle (char-based approximation)

Getting Started

Prerequisites

• Node.js v18+ (ES modules)
• npm v9+
• OpenCode with TUI plugin support

Installation

From npm (recommended)

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["@jimicze-opencode/opencode-tps"]
}

Or via CLI:

opencode plugin @jimicze-opencode/opencode-tps

OpenCode auto-installs and caches it — no manual setup needed.

From source (development)

git clone <repo-url> ~/.config/opencode/plugins/tps

Register in .opencode/tui.json:

{
  "plugin": ["./plugins/tps-plugin.tsx"]
}

Restart OpenCode. The plugin loads automatically.

No build step — OpenCode loads .tsx directly at runtime.

Metrics

| Metric | Idle | Prefilling | Generating | Complete | |--------|------|------------|------------|---------| | Total | 1,234 total | 0 out | 42 out | 1,234 total | | PP | -- | ... (blue) | 512 tok/s (avg) | 512 tok/s (avg) | | TG | -- | ... (green) | 63 tok/s (cur) (green) | 63 tok/s (avg) | | Cache | hidden | hidden | hidden | 200 tok | | Reasoning | hidden | hidden | hidden | 30 tok |

Calculation

• PP Speed = input tokens / prefill time (authoritative from step-finish)
• TG Speed = output tokens / generation time (authoritative from step-finish)
• Live TG = chars generated / time since first token (approximate; no tokenizer access in TUI)
• Session Totals = cumulative across all assistant messages, never reset

Configuration

Create .opencode/plugins/tps-config.json to customize display:

{
  "showTotal": true,
  "showPpSpeed": true,
  "showTgSpeed": true,
  "showCache": true,
  "showReasoning": true,
  "liveIntervalMs": 150
}

| Option | Default | Description | |--------|---------|-------------| | showTotal | true | Show total token count | | showPpSpeed | true | Show PP speed | | showTgSpeed | true | Show TG speed | | showCache | true | Show cache tokens (when > 0) | | showReasoning | true | Show reasoning tokens (when available) | | liveIntervalMs | 150 | Live TG speed update interval (ms, clamped to >= 50) |

Project Structure

.
├── .opencode/
│   ├── plugins/
│   │   ├── tps-plugin.tsx          # Source (457 lines)
│   │   └── tps-plugin.test.ts      # Tests (2974 lines)
│   ├── tui.json                    # Plugin registration
│   ├── tsconfig-check.json         # TypeScript config
│   └── opencode.json               # OpenCode config
├── package.json                    # Dev dependencies
├── vitest.config.ts                # Test config
└── .gitignore                      # Ignores docs/, AGENTS.md, .opencode/*.md

## Development

### Setup

```shell
npm install        # install vitest + typescript

Test

npm test           # vitest run — 163 tests
npm run test:watch # watch mode

TypeCheck

npm run typecheck  # tsc --noEmit via tsconfig-check.json

No lint or format tool configured — the project is intentionally minimal (1 source file).

Test Coverage

| Suite | Tests | Focus | |-------|-------|-------| | createTracker | ~80 | Guards, state transitions, accumulation, formatting, interval | | accumulateTokens | 5 | Subagent-safe accumulation, speed preservation, nesting | | chaos scenarios | 7 | Timeouts, reconnects, stale events, interleaved failures | | event handlers | ~70 | All 4 handlers, malformed data, subagent routing, stale rejection | | Total | 163 | 120 negative, 43 positive |

Test philosophy: negative tests outnumber positive. Every guard, edge case, and failure mode is tested before the happy path.

Troubleshooting

Plugin not showing in sidebar

• Check .opencode/tui.json has the correct path to ./plugins/tps-plugin.tsx
• Verify ~/.local/state/opencode/plugin-meta.json shows tps.status with a load count
• Restart OpenCode — plugins load at session start

Metrics look wrong

• PP speed is very high — normal with fast models; prefill time can be < 20ms
• TG speed drops to zero — step-finish was likely missed; a fallback from session.status or message.updated is used instead
• Cache is zero — some providers don't report cache tokens; this is expected
• Session totals include subagent tokens — by design; subagent work contributes to the session total

Debug logs not visible

• console.log from the plugin goes to the TUI/browser console, not opencode.log
• Look for [TPS]-prefixed messages in the browser console

Known Limitations

• Live TG speed is approximate — uses char count as a proxy for tokens (no tokenizer access in TUI)
• Session totals reset on OpenCode restart — this is intentional (session-level, not global)
• Idle fallback may slight double-count — if step-finish arrives after idle fallback ran, the char proxy and authoritative tokens both accumulate. Acceptable trade-off for an edge case.
• No formatter/linter configured — project is intentionally minimal

Contributing

The project uses a test-driven approach with extensive negative testing. See the test file for conventions, and the .opencode/ agent context files if you have access to them.

Backlog

Top candidates for future work:

• Per-model speed tracking
• UI polish (prefill spinner, toggle sidebar/footer)
• Cost estimation (if token pricing is available from API)
• Config option to reset session totals

License

MIT — see LICENSE.