Claude Code Cockpit

See exactly what your Claude Code usage costs — two ways, both local, both free.

1. cc-usage CLI — a zero-dependency Python script that reads the transcripts Claude Code already writes and prints token + cost accounting, sliced by day, session, agent, skill, MCP server, plugin, project, or model. No setup, no Docker.
2. Live Grafana dashboard — a one-command Docker stack (OpenTelemetry + Prometheus
   • Loki + Grafana) with a prebuilt dashboard that updates in real time as you work, including "Max Plan Leverage" and "Signal vs Noise" panels.

Everything runs on your machine. Your usage data never leaves it.

---

Quick start — the CLI (10 seconds, no dependencies)

python3 cli/cc-usage.py --days 1 --cost        # today, with USD
python3 cli/cc-usage.py --by agent --cost      # which subagent burned the tokens
python3 cli/cc-usage.py --by project --cost    # spend by project
python3 cli/cc-usage.py --watch 5 --by session --cost   # live, refresh every 5s

Optional alias:

alias ccu="python3 $(pwd)/cli/cc-usage.py"

Full flag reference: cli/README.md. Requires Python 3.11+.

USD is equivalent on-demand API list price. On a Pro/Max plan your real marginal cost is $0 up to plan limits — the figure shows what the same work would cost a la carte. Treat it as a floor, not a ceiling.

---

Quick start — the live dashboard

The easy way — let Claude Code do it. Open this folder in Claude Code and say:

set up the dashboard

It reads CLAUDE.md and does the rest: starts Docker, brings up the stack, wires the telemetry env vars into your Claude settings, and opens Grafana.

The manual way:

./setup.sh dashboard          # starts the stack, prints the telemetry config

Then add the telemetry vars (printed by setup.sh, also in .env.example) to ~/.claude/settings.json under "env", start a new Claude Code session, and open:

• Grafana: http://localhost:3000 · login admin / admin
• Prometheus: http://localhost:9090

Stop it anytime with dashboard/down.sh. Full details: dashboard/README.md.

Requirements

• Docker Desktop running — download: https://www.docker.com/products/docker-desktop/ (macOS + Homebrew: brew install --cask docker; lighter alternative: OrbStack)
• Ports 3000, 9090, 4317, 4318 free

Setup checks both for you — if Docker is missing or stopped, the wizard shows you exactly what to do before continuing.

---

Which one should I use?

	CLI (cc-usage)	Live dashboard
Setup	none	Docker + telemetry env
Data source	local transcripts (always complete, incl. history)	live OTel stream (from when the stack is up)
Best for	quick checks, scripting, historical totals	watching cost in real time while you work
Attribution by agent/skill/project	✅	partial

They complement each other: the CLI gives you the full historical ledger with no moving parts; the dashboard gives you a live cockpit while you're at the keyboard.

---

Repository layout

cli/
  cc-usage.py          # the accounting CLI (MIT, © Paul Takisaki)
  README.md            # CLI docs + flags
  automation/          # optional launchd/cron rollups & snapshots
dashboard/             # live Grafana stack — derivative of ColeMurray/claude-code-otel (MIT)
CLAUDE.md              # setup instructions Claude Code follows
setup.sh               # manual installer
.env.example           # telemetry env vars for the dashboard

---

Credits & license

The cli/ tools (cc-usage) are original work by Paul Takisaki, MIT licensed.

The dashboard/ is a derivative of the excellent Claude Code Observability Stack by Cole Murray, used under the MIT License. Its original license is retained at dashboard/LICENSE. If the dashboard is useful to you, please star the upstream project. See NOTICE for full attribution.

This repository is MIT licensed — see LICENSE.