Metadata-Version: 2.4
Name: tokenwatch
Version: 0.2.4
Summary: Real-time Claude Code cost dashboard — know exactly what you're spending
License: MIT
Project-URL: Homepage, https://tokenwatch.dev
Project-URL: Issues, https://github.com/yourusername/tokenwatch/issues
Keywords: claude,anthropic,llm,cost,tokens,dashboard
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# TokenWatch 👀

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

**[tokenwatch.observer](https://tokenwatch.observer)** · [Report a bug](https://github.com/lorenzogiarnese-hash/tokenwatch/issues)

---

## Install

```bash
pip install tokenwatch
```

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

## Run

```bash
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 hello@tokenwatch.observer

---

## Commands

```bash
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
bash install_autostart.sh
```

**Linux (systemd):**
```bash
# 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 →](https://tokenwatch.observer/#pricing)

---

## Cancel subscription

Go to ⚙ Settings in the dashboard → **Manage subscription** (Pro users only). Or email info@consulting-ai.tech.

---

## 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
