/throughput

name: throughput
description: Use when the user asks to open/show the CCC throughput (token) dashboard, or asks how many tokens they've used — overall/so far, in the last 7 days, or for a specific session (e.g. "how many tokens is session ffbbeef8", "open throughput dashboard", "what's my token burn"). Answers token/cost questions from CCC's throughput API and links the page.

Throughput

CCC's **throughput dashboard** (`static/throughput.html`, served at `/throughput.html`) charts token usage, TPM/TPS, cost, and cache-hit ratio — for a 7-day aggregate or per session. There is **no dedicated CLI**; the numbers come from the dashboard's HTTP API (`/api/throughput`).

This skill wraps both behind one helper: `throughput.sh` (next to this file). It resolves the running dashboard's port, and — because the API needs a *full* session id — resolves an 8-char prefix like `ffbbeef8` to the full uuid first.

Run it from the skill directory, e.g.:

.claude/skills/throughput/throughput.sh <subcommand>

Requests → what to do

**"open throughput dashboard" / "show me throughput" / "the token page"** Run `throughput.sh url` and give the user the `throughput.html` link (it's clickable in the terminal). Only actually launch a browser if they say "open it" *and* a browser opener is available — `xdg-open <url>` (Linux) or `open <url>` (macOS); otherwise just hand over the URL. Don't assume a GUI.

**"how many tokens have I used / so far / this week" / "what's my burn"** Run `throughput.sh total`. This is the **Last-7-days aggregate** across all Claude sessions (CCC only retains a 7-day throughput window — say "last 7 days", not "all time"). Relay the total, the input/output split, cache-hit %, and cost.

**"how many tokens is session ffbbeef8" / "tokens for <id>"** Run `throughput.sh session <id-or-prefix>`. A short prefix is fine — the helper resolves it. If it prints "No session matches", the id isn't in the current conversation list (wrong prefix, or older than the 7-day window) — tell the user that rather than guessing.

Engines

Default engine is `claude`. For Codex/other engines pass it as the last arg: `throughput.sh total codex`, `throughput.sh session <id> codex`. If the user doesn't name an engine, use `claude`.

Notes

• **Base URL / port:** the helper auto-detects the live `server.py` port (this

isn't always 8090). Override with `CCC_BASE_URL=http://host:port` if CCC runs elsewhere (e.g. over Tailscale).

• **Dashboard must be running.** If every probe fails, the CCC dashboard isn't

up — say so; don't fabricate numbers.

• Numbers are read-only. This skill never writes or restarts anything, so the

restart matrix is **N/N/N**.