tokwave 🌊

Live token/s waveform visualizer for Claude Code.

Inspired by @chrisbarber's agent UI explorations (151K impressions).

┌─────────────────────────────────────────────────────┐
│  tokwave — tok/s over time                          │
│                                                     │
│  800 ┤                    ╭──╮                      │
│  600 ┤         ╭──╮      ╭╯  ╰──╮    ╭╮            │
│  400 ┤   ╭╮   ╭╯  ╰──╮  ╭╯     ╰╮  ╭╯╰╮           │
│  200 ┤──╮╰╰──╮╯       ╰──╯       ╰──╯  ╰──         │
│    0 └──────────────────────────────────── time     │
│       -120s                              now        │
├──────────────────────┬──────────────────────────────┤
│  ▁▂▄▇█▅▃▂▁▁▂▄▅▇█▄  │  Total tokens:  127.4K       │
│  tok/s sparkline     │  Current rate:  412 tok/s    │
│                      │  Active tool:   Bash         │
│                      │  Session:       abc123...    │
├──────────────────────┴──────────────────────────────┤
│  tool calls                                         │
│  15:43:22 Bash           +2.1K tok                  │
│  15:43:25 Read           +840 tok                   │
│  15:43:31 Edit           +1.2K tok                  │
└─────────────────────────────────────────────────────┘

Quick Install

# One-liner
curl -fsSL https://raw.githubusercontent.com/Gonzih/tokwave/main/install.sh | bash

# Or manual
npm install -g tokwave

Usage

1. Terminal waveform UI

tokwave

Renders live waveform in your terminal. Press q to quit, c to clear.

2. Claude Code hook (auto-captures token events)

The installer adds this to ~/.claude/settings.json automatically:

{
  "hooks": {
    "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "tokwave-hook" }] }],
    "PreToolUse":  [{ "matcher": "", "hooks": [{ "type": "command", "command": "tokwave-hook" }] }]
  }
}

3. MCP server (query stats from inside Claude)

claude mcp add tokwave -- npx tokwave-mcp

Then in any Claude Code session:

> what's my current token rate?
[calls get_token_stats]
> Total tokens: 127.4K, current rate: 412 tok/s, top tool: Bash (84K tok)

Architecture

Claude Code
  │
  ├── PreToolUse hook  ──► tokwave-hook (stdin: JSON event)
  ├── PostToolUse hook ──► tokwave-hook (stdin: JSON event)
  │                              │
  │                              ▼
  │                    /tmp/tokwave-events.jsonl
  │                         (ring buffer, 500 events)
  │                              │
  └── tokwave CLI  ◄─────────────┘
       │  (polls file, 500ms refresh)
       │
       ▼
  blessed terminal UI
  ├── waveform (tok/s per second, 120s window)
  ├── sparkline (last 20s)
  ├── stats box
  └── tool call log

MCP Tools

| Tool | Description | |------|-------------| | get_token_stats | Total tokens, current rate, top tools | | get_waveform | Last N seconds of tok/s buckets | | clear_stats | Reset the ring buffer |

Discovery

• npm: npm install -g tokwave
• GitHub: Gonzih/tokwave
• Claude Code MCP registry: searchable via claude mcp search tokwave
• awesome-claude-code: submit PR to jqueryscript/awesome-claude-code

Inspired by

Chris Barber's agent UI explorations thread — waveform showing tok/s as the primary visual metaphor for "how hard is my agent working right now."

License

MIT