tokenwatch 0.2.3

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.

tokenwatch.observer · Report a bug

---

Install

pip install tokenwatch

Requires Python 3.11+ · Works on macOS, Linux, Windows

Run

tokenwatch

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

---

Troubleshooting — I see no data

Run the built-in diagnostic:

Visit http://localhost:7842/api/debug in your browser after starting TokenWatch. It checks:

• Whether your Claude Code log directory exists
• Whether session files are present
• Whether the log format is readable
• What the most recent session contains

Common fixes:

Problem	Fix
"No .jsonl files found"	Run claude in a project folder first, then refresh
"Claude projects directory not found"	Claude Code hasn't been used yet on this machine
Dashboard shows $0.00	Your session has no usage data — check the diagnostic
Numbers look wrong	Click ↺ Refresh on the prices panel to fetch live rates

Still stuck? Open an issue on GitHub or email [e-mail]

---

Commands

tokenwatch                   # start dashboard + open browser
tokenwatch status            # print today's cost in terminal
tokenwatch export            # export 30 days to CSV (Pro)
tokenwatch seed              # generate demo data
tokenwatch seed --clean      # remove demo data
tokenwatch config            # show current settings
tokenwatch license --key tw_live_...   # activate Pro license

Auto-start on login

macOS:

bash install_autostart.sh

Linux (systemd):

# Create ~/.config/systemd/user/tokenwatch.service
[Unit]
Description=TokenWatch

[Service]
ExecStart=/usr/local/bin/tokenwatch --no-browser
Restart=always

[Install]
WantedBy=default.target

# Enable
systemctl --user enable tokenwatch
systemctl --user start tokenwatch

Windows: Coming soon. For now, add tokenwatch --no-browser to your startup folder.

---

Configuration

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

Key	Default	Description
daily_budget	10.00	Daily spend limit (USD)
alert_at_pct	[80, 100]	Notification thresholds (Pro: customizable)
history_days	7	Days of history (Free: max 7, Pro: max 90)
port	7842	Server port
open_browser	true	Auto-open on start
digest_email	""	Weekly email (Pro + RESEND_API_KEY required)

---

Free vs Pro

Feature	Free	Pro ($9/mo)
Live cost dashboard	✓	✓
7-day history	✓	✓
Budget alerts	✓	✓
Session drill-down	✓	✓
Project breakdown	✓	✓
90-day history	—	✓
CSV / JSON export	—	✓
Weekly email digest	—	✓
Custom alert thresholds	—	✓

Get Pro →

---

Cancel subscription

Go to ⚙ Settings in the dashboard → Manage subscription (Pro users only). Or email [e-mail].

---

How it works

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

Costs = token counts × live Anthropic prices (fetched from LiteLLM's community-maintained price list).

---

License

MIT