pi-token-speed

A Pi Coding Agent extension that displays real-time tokens-per-second (TPS) performance metrics in the status bar while the AI is streaming responses.

Features

• Real-time TPS tracking — measures token throughput as the assistant generates text and thinking content
• Time-to-first-token (TTFT) — measures latency from user message to the first token being generated
• Configurable sliding window — adjust the window size to suit your server speed (default: 1s)
• Color-coded speed indicators — visual feedback based on performance thresholds
• Provider-reported counting — opt in to using provider-reported counts (e.g. Anthropic, OpenAI) instead of the extension's own counter
• Fully configurable — customize display, thresholds and colors via ~/.pi/agent/settings.json

Speed Tiers

| Tier | TPS | Color | | ---------- | ----- | ------------------ | | 🟥 Slow | 0–15 | #ff4444 (red) | | 🟨 Medium | 15–30 | #ffaa00 (orange) | | 🟩 Fast | 30–45 | #00ff88 (green) | | 🟦 Blazing | 45+ | #44ddff (cyan) |

Installation

This package is a Pi extension. Install it with

npm install pi-token-speed

or

pi install https://github.com/gsanhueza/pi-token-speed

Configuration

You can customize the display, speed thresholds and colors by adding a tokenSpeed section to your ~/.pi/agent/settings.json:

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

Configuration Options

| Option | Type | Default | Description | | ------------------- | ------------------------------ | ----------- | ---------------------------------------------------------------------------- | | display | tps, ttft, stats, full | tps | Which metrics to display (see Display Modes below) | | tpsSlow | number | 0 | Minimum TPS threshold ("slow") | | tpsMedium | number | 15 | TPS above this is "medium" | | tpsFast | number | 30 | TPS above this is "fast" | | tpsBlazing | number | 45 | TPS above this is "blazing" | | colorSlow | string | "#ff4444" | Color for slow tier | | colorMedium | string | "#ffaa00" | Color for medium tier | | colorFast | string | "#00ff88" | Color for fast tier | | colorBlazing | string | "#44ddff" | Color for blazing tier | | slidingWindow | number | 1000 | Sliding window duration in ms | | useProviderTokens | boolean | false | Opt-in: use provider-reported counts instead of this extension's own counter | | countStrategy | estimate, direct | direct | Token counting strategy used by the extension's own counter |

Interactive Menu

A small interactive menu is available when running /tps in the editor, where you can adjust:

• Display mode — what to show in the status bar
• Use provider tokens — use provider-reported counts instead of the extension's counter
• Count strategy — how the extension counts tokens (estimate or direct)

Sliding Window

The sliding window determines how many recent tokens are used to calculate TPS. A larger window produces smoother readings at the cost of responsiveness; a smaller window reacts faster but can be noisier.

| Server speed | Recommended window | Why | | ------------------- | ------------------ | --------------------------------------------------------- | | Fast (30+ tok/s) | 1000 (default) | Plenty of tokens in the window — accurate and responsive | | Medium (5–30 tok/s) | 1000–3000 | Enough tokens for stable readings | | Slow (< 5 tok/s) | 5000–15000 | Captures more tokens, avoiding spiky or unreliable values |

For example, if your server streams at ~1 tok/s, a 10-second window gives ~10 tokens per window — enough for a reasonable calculation:

{
  "tokenSpeed": {
    "slidingWindow": 10000
  }
}

Provider Token Counts

By default, this extension uses its own token counter — the same engine behind countStrategy. As an alternative, you can opt in to using the provider's own reported counts instead:

| Value | Behavior | | ----------------- | ------------------------------------------------------------------------------------------- | | false (default) | Use this extension's own counter (controlled by countStrategy) | | true | Use the provider's reported counts instead; fall back to countStrategy when not available |

The extension's own counter is the default and always available. Enable useProviderTokens: true when your provider reports accurate token counts and you'd prefer to use them instead.

Count Strategy

When useProviderTokens is false (default) or when the provider doesn't report counts, the countStrategy determines how the extension's own counter works:

| Strategy | Behavior | | ------------------ | ----------------------------------- | | direct (default) | Counts each delta as 1 token | | estimate | Approximates tokens from delta text |

The direct strategy is fast and preserves the original behavior — it counts each streaming delta as 1 token, including toolcalls for edit and write operations. Use estimate when your server streams in small chunks — it approximates the real token count from the delta text, giving a more meaningful TPS reading.

Display Modes

| Mode | Description | | ------- | --------------------------------------------------------------------------- | | tps | ⚡ TPS: 25.0 tok/s — TPS with color-coded speed tier | | ttft | ⚡ TPS: 25.0 tok/s (TTFT: 450 ms) — TPS + time-to-first-token | | stats | ⚡ TPS: 25.0 tok/s (150 tok in 6.0s) — TPS + token count and elapsed time | | full | ⚡ TPS: 25.0 tok/s (150 tok in 6.0s · TTFT: 450 ms) — everything |

Commands

| Command | Description | | ------- | -------------------------------------------------------------------------------- | | /tps | Open settings menu — configure display mode, provider tokens, and count strategy |

How It Works

1. Session Start — Renders the initial status bar entry showing ⚡ TPS: --
2. Message Start — When the assistant begins streaming, the engine starts tracking
3. TTFT Measurement — When the user message starts, a timer begins. The moment the first token (text, thinking, or tool call) is emitted, the elapsed time is recorded as the time-to-first-token (TTFT) in milliseconds
4. Token Update — Each text/thinking delta is recorded. If useProviderTokens is true and the provider reports token counts, those are used directly; otherwise the extension's own counter (controlled by countStrategy) is used
5. Sliding Window — TPS is calculated using a configurable time window of token timestamps
6. Message End — The authoritative token count (if available) is used to snap the total, ensuring the final average is exact

Dependencies

| Peer dependency | Purpose | | --------------------------------- | ------------------- | | @earendil-works/pi-coding-agent | Pi Coding Agent SDK | | @earendil-works/pi-tui | Pi TUI SDK |