Metadata-Version: 2.4
Name: tokenwatch
Version: 0.2.2
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.

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

---

## Install

```bash
pip install tokenwatch
```

## Run

```bash
tokenwatch
```

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

## Commands

```bash
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

```bash
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

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

## Auto-start on macOS login

```bash
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

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

Or manually:
```bash
make publish
```

## License

MIT
