tokenwatch-docs

Troubleshooting

Run the built-in diagnostic first

Before anything else, open this URL in your browser while TokenWatch is running:

http://localhost:7842/api/debug

It checks your setup automatically and tells you exactly what’s wrong.

I see no data in the dashboard

Check 1 — Have you used Claude Code yet?

TokenWatch reads logs that Claude Code writes. If you’ve never run claude in a project folder, there are no logs yet.

Fix: run claude in any project folder, have a short conversation, then refresh the dashboard.

Check 2 — Is the log directory in the right place?

TokenWatch looks for logs at ~/.claude/projects/. Run this to check:

ls ~/.claude/projects/

If the folder doesn’t exist or is empty, Claude Code hasn’t generated logs yet.

Check 3 — Generate demo data to test the dashboard

tokenwatch seed

This creates 30 days of realistic fake data. If the dashboard shows data after this, the tool works — you just need real Claude Code sessions.

Remove demo data when done:

tokenwatch seed --clean

The cost shows $0.00

This means TokenWatch found session files but couldn’t read usage data from them.

Most likely cause: you’re using a Claude Code version with a different log format.

Fix: open http://localhost:7842/api/debug — it will tell you if usage data was found in your logs.

If the issue persists, open an issue at tokenwatch.observer with the output of the debug endpoint.

“tokenwatch: command not found”

Your Python scripts folder is not in your PATH.

Fix:

# Find where pip installs scripts
python3 -m site --user-base

# Add to PATH (add this to your ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$(python3 -m site --user-base)/bin"

# Reload
source ~/.zshrc

The dashboard doesn’t open automatically

Run manually:

tokenwatch --no-browser

Then open http://localhost:7842 in your browser.

Port 7842 is already in use

tokenwatch --port 8080

Or change it permanently in Settings → Advanced → Server port.

Prices show “Using hardcoded fallback”

TokenWatch couldn’t fetch live prices. This happens when:

You’re offline
The price source (LiteLLM) is temporarily unavailable

Fix: click ↺ Refresh in the prices panel. Your costs are still calculated — just using cached or fallback prices which are usually accurate.

I can’t find my license key email

Check your spam folder. The email comes from hello@tokenwatch.observer.

If you still can’t find it, email info@consulting-ai.tech with your payment confirmation and we’ll resend it within 24 hours.

How do I cancel my Pro subscription?

Open TokenWatch → ⚙ Settings → Manage subscription. You can cancel, update your payment method, and download invoices — all without contacting support.

Or email info@consulting-ai.tech and we’ll handle it for you.