tokenwatch 0.2.2

Real-time Claude Code cost dashboard — know exactly what you're spending

TokenWatch

Real-time Claude Code cost dashboard. Know exactly what you're spending — per session, per project, per day.

No proxy. No SDK wrapping. No API key required. Reads Claude Code's local session logs directly.

---

Install

pip install tokenwatch

Run

tokenwatch

Opens http://localhost:7842 automatically. That's it.

Commands

tokenwatch                   # start dashboard + open browser
tokenwatch start             # same as above
tokenwatch status            # print today's cost in terminal
tokenwatch export            # export 30 days to CSV
tokenwatch export --format json --days 90
tokenwatch seed              # generate demo data (no real logs needed)
tokenwatch seed --clean      # remove demo data
tokenwatch config            # show current settings

Options

tokenwatch --budget 20       # set $20/day budget
tokenwatch --port 8080       # different port
tokenwatch --no-browser      # don't open browser

Features

• Live cost meter — updates in real time as Claude Code responds
• Daily budget bar — turns orange at 80%, red at 100%
• Desktop notifications — alerts at configurable thresholds (macOS, Linux)
• Session drill-down — click any session to see per-message cost breakdown
• Project breakdown — doughnut chart showing cost by project
• CSV/JSON export — one-click download
• Live pricing — fetched from Anthropic on startup, cached locally
• Weekly email digest — optional (requires RESEND_API_KEY)
• Auto-start on login — run bash install_autostart.sh once (macOS)

Configuration

Settings live in ~/.claude/tokenwatch_config.json. Edit directly or use the ⚙ button in the dashboard.

Key	Default	Description
daily_budget	10.00	Daily spend limit (USD)
alert_at_pct	[80, 100]	Notification thresholds
history_days	30	Days of history to show
port	7842	Server port
open_browser	true	Auto-open on start
digest_email	""	Weekly email (needs RESEND_API_KEY)

Weekly digest email

export RESEND_API_KEY=re_...
tokenwatch  # set digest_email in Settings

Auto-start on macOS login

bash install_autostart.sh

How it works

Claude Code writes JSONL session logs to ~/.claude/projects/<project>/<session>.jsonl. TokenWatch watches that directory with OS-native file events (FSEvents on macOS, inotify on Linux), reads new entries within 300ms, and streams cost updates to the dashboard via Server-Sent Events.

Costs = token counts × live Anthropic prices. Cache tokens are priced correctly (10× cheaper than input).

Publishing to PyPI

# Tag a release
git tag v0.2.0 && git push --tags
# GitHub Actions auto-publishes via trusted publishing

Or manually:

make publish

License

MIT