tokenwatch 0.2.0__tar.gz

tokenwatch-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: tokenwatch
+Version: 0.2.0
+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

tokenwatch-0.2.0/README.md

@@ -0,0 +1,106 @@
+# 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

tokenwatch-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenwatch"
+version = "0.2.0"
+description = "Real-time Claude Code cost dashboard — know exactly what you're spending"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["claude", "anthropic", "llm", "cost", "tokens", "dashboard"]
+dependencies = [
+    "fastapi>=0.111",
+    "uvicorn[standard]>=0.29",
+    "watchdog>=4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build", "twine"]
+
+[project.scripts]
+tokenwatch = "tokenwatch.cli:main"
+
+[project.urls]
+Homepage = "https://tokenwatch.dev"
+Issues   = "https://github.com/yourusername/tokenwatch/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tokenwatch*"]
+
+[tool.setuptools.package-data]
+"tokenwatch" = ["static/*"]

tokenwatch-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenwatch-0.2.0/tokenwatch/__init__.py

@@ -0,0 +1,2 @@
+"""TokenWatch — Real-time Claude Code cost dashboard."""
+__version__ = "0.2.0"

tokenwatch-0.2.0/tokenwatch/alerts.py

@@ -0,0 +1,142 @@
+"""
+alerts.py — Desktop notifications + weekly email digest.
+
+Notifications work on:
+  macOS   — osascript
+  Linux   — notify-send (libnotify)
+  Windows — win10toast or plyer fallback
+
+Email digest uses Resend (free tier: 3000 emails/mo).
+Set RESEND_API_KEY env var + digest_email in config to enable.
+"""
+
+import logging
+import os
+import platform
+import subprocess
+from datetime import date, timedelta
+
+logger = logging.getLogger(__name__)
+
+
+# ── Desktop notifications ─────────────────────────────────────────────────────
+
+def notify(title: str, message: str) -> None:
+    """Send a desktop notification. Silently fails if not supported."""
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            script = f'display notification "{message}" with title "{title}" sound name "Tink"'
+            subprocess.run(["osascript", "-e", script], capture_output=True, timeout=3)
+
+        elif system == "Linux":
+            subprocess.run(
+                ["notify-send", title, message, "--app-name=TokenWatch", "--icon=dialog-information"],
+                capture_output=True, timeout=3,
+            )
+
+        elif system == "Windows":
+            try:
+                from win10toast import ToastNotifier
+                ToastNotifier().show_toast(title, message, duration=5, threaded=True)
+            except ImportError:
+                try:
+                    import plyer
+                    plyer.notification.notify(title=title, message=message, app_name="TokenWatch")
+                except ImportError:
+                    logger.debug("No Windows notification library available (win10toast / plyer).")
+
+    except Exception as e:
+        logger.debug(f"Notification failed: {e}")
+
+
+# ── Budget alert state ────────────────────────────────────────────────────────
+
+_alert_sent: set[str] = set()
+
+
+def check_budget(cost: float, budget: float, thresholds: list[int]) -> None:
+    """Fire a notification when cost crosses a budget threshold."""
+    today = str(date.today())
+    for pct in thresholds:
+        key = f"{today}-{pct}"
+        if cost >= budget * (pct / 100) and key not in _alert_sent:
+            _alert_sent.add(key)
+            msg = f"${cost:.2f} spent today — {pct}% of your ${budget:.0f} budget"
+            notify("TokenWatch Budget Alert", msg)
+            logger.info(f"Budget alert sent: {pct}%")
+
+
+def reset_alerts() -> None:
+    """Call at midnight to allow today's alerts to fire again tomorrow."""
+    _alert_sent.clear()
+
+
+# ── Weekly email digest ───────────────────────────────────────────────────────
+
+def send_weekly_digest(to_email: str, sessions_data: list[dict]) -> bool:
+    """
+    Send a weekly cost summary email via Resend.
+    Requires RESEND_API_KEY environment variable.
+    Returns True on success.
+    """
+    api_key = os.environ.get("RESEND_API_KEY", "")
+    if not api_key or not to_email:
+        logger.debug("Digest skipped: no RESEND_API_KEY or no email configured.")
+        return False
+
+    try:
+        import urllib.request, json as _json
+
+        total = sum(s.get("total_cost", 0) for s in sessions_data)
+        week_ago = str(date.today() - timedelta(days=7))
+        top_projects: dict[str, float] = {}
+        for s in sessions_data:
+            p = s.get("project", "unknown")
+            top_projects[p] = round(top_projects.get(p, 0) + s.get("total_cost", 0), 4)
+
+        top = sorted(top_projects.items(), key=lambda x: x[1], reverse=True)[:5]
+        rows = "".join(
+            f"<tr><td style='padding:6px 12px;border-bottom:1px solid #eee'>{p}</td>"
+            f"<td style='padding:6px 12px;border-bottom:1px solid #eee;text-align:right'>${c:.4f}</td></tr>"
+            for p, c in top
+        )
+
+        html = f"""
+        <div style="font-family:-apple-system,sans-serif;max-width:480px;margin:0 auto;color:#1a1a18">
+          <h2 style="font-size:18px;font-weight:500;margin-bottom:4px">Your Claude Code spend last week</h2>
+          <p style="color:#6b6a64;margin-bottom:24px;font-size:13px">{week_ago} → {date.today()}</p>
+          <div style="background:#f8f7f4;border-radius:12px;padding:20px;margin-bottom:20px;text-align:center">
+            <p style="font-size:36px;font-weight:500;margin:0">${total:.2f}</p>
+            <p style="color:#6b6a64;font-size:13px;margin:4px 0 0">{len(sessions_data)} sessions</p>
+          </div>
+          <p style="font-size:12px;font-weight:500;text-transform:uppercase;letter-spacing:.05em;color:#6b6a64;margin-bottom:8px">By project</p>
+          <table style="width:100%;border-collapse:collapse;font-size:13px">{rows}</table>
+          <p style="margin-top:24px;font-size:12px;color:#6b6a64">
+            TokenWatch · <a href="http://localhost:7842" style="color:#178BCA">Open dashboard</a>
+          </p>
+        </div>
+        """
+
+        payload = _json.dumps({
+            "from":    "TokenWatch <digest@tokenwatch.dev>",
+            "to":      [to_email],
+            "subject": f"Your Claude Code bill last week: ${total:.2f}",
+            "html":    html,
+        }).encode()
+
+        req = urllib.request.Request(
+            "https://api.resend.com/emails",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type":  "application/json",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            logger.info(f"Digest sent to {to_email} (status {resp.status})")
+            return True
+
+    except Exception as e:
+        logger.warning(f"Digest send failed: {e}")
+        return False

tokenwatch-0.2.0/tokenwatch/cli.py

@@ -0,0 +1,170 @@
+"""
+cli.py — `tokenwatch` command.
+
+tokenwatch              start dashboard
+tokenwatch start        start dashboard
+tokenwatch status       print today's cost
+tokenwatch export       export to CSV/JSON
+tokenwatch seed         generate demo data
+tokenwatch seed --clean remove demo data
+tokenwatch config       show config
+tokenwatch license      activate Pro license
+"""
+
+import argparse
+import sys
+import threading
+import webbrowser
+
+
+def cmd_start(args) -> None:
+    from tokenwatch import config as cfg_module
+    import uvicorn
+
+    cfg = cfg_module.load()
+    if args.budget is not None:
+        cfg["daily_budget"] = args.budget
+        cfg_module.save(cfg)
+    if args.port:
+        cfg["port"] = args.port
+        cfg_module.save(cfg)
+
+    port         = cfg["port"]
+    open_browser = cfg["open_browser"] and not args.no_browser
+    url          = f"http://localhost:{port}"
+
+    from tokenwatch import __version__
+    print(f"\n  ● TokenWatch v{__version__}")
+    print(f"  Dashboard → {url}")
+    print(f"  Budget    → ${cfg['daily_budget']:.2f}/day")
+    print(f"  Press Ctrl+C to stop\n")
+
+    if open_browser:
+        threading.Timer(1.4, lambda: webbrowser.open(url)).start()
+
+    uvicorn.run("tokenwatch.main:app", host="127.0.0.1", port=port, log_level="warning")
+
+
+def cmd_status(args) -> None:
+    from tokenwatch.parser import get_daily_summary, get_today_cost
+    from tokenwatch import config as cfg_module
+
+    cfg    = cfg_module.load()
+    budget = cfg.get("daily_budget", 10.0)
+    cost   = get_today_cost()
+    pct    = cost / budget * 100 if budget else 0
+    summary = get_daily_summary(days=7)
+    max_cost = max((d["cost"] for d in summary), default=1) or 1
+
+    print(f"\n  TokenWatch — today")
+    print(f"  Spent   : ${cost:.4f}  ({pct:.1f}% of ${budget:.0f} budget)")
+    if summary:
+        print(f"\n  Last 7 days:")
+        for d in summary[-7:]:
+            bar = "█" * int(d["cost"] / max_cost * 20)
+            print(f"  {d['date']}  {bar:<20} ${d['cost']:.4f}")
+    print()
+
+
+def cmd_export(args) -> None:
+    from tokenwatch.parser import export_csv, get_all_sessions
+    from pathlib import Path
+    import json
+
+    if args.format == "csv":
+        out = export_csv(days=args.days)
+        fname = "tokenwatch-export.csv"
+        Path(fname).write_text(out)
+        print(f"Exported to {fname}")
+    else:
+        data = [s.to_dict() for s in get_all_sessions(days=args.days)]
+        fname = "tokenwatch-export.json"
+        Path(fname).write_text(json.dumps(data, indent=2))
+        print(f"Exported {len(data)} sessions to {fname}")
+
+
+def cmd_seed(args) -> None:
+    from tokenwatch import seed_demo
+    if args.clean:
+        seed_demo.clean()
+    else:
+        seed_demo.generate(days=args.days)
+
+
+def cmd_config(args) -> None:
+    from tokenwatch import config as cfg_module
+    cfg = cfg_module.load()
+    print(f"\n  Config → {cfg_module.CONFIG_FILE}\n")
+    for k, v in cfg.items():
+        if k == "license_key" and v:
+            v = v[:4] + "…" + v[-4:] if len(v) >= 8 else "set"
+        print(f"  {k:<22} {v}")
+    print()
+
+
+def cmd_license(args) -> None:
+    from tokenwatch.license_check import validate
+    from tokenwatch import config as cfg_module
+
+    key = args.key or input("Enter your license key: ").strip()
+    if not key:
+        print("No key entered.")
+        return
+
+    print("Validating…")
+    result = validate(key)
+
+    if result["valid"]:
+        cfg = cfg_module.load()
+        cfg["license_key"] = key
+        cfg_module.save(cfg)
+        print(f"✓ License activated ({result['plan']} plan)")
+    else:
+        print(f"✗ Invalid license: {result.get('message', '')}")
+        print("  Get a license at https://tokenwatch.dev")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="tokenwatch", description="Real-time Claude Code cost dashboard")
+    sub = parser.add_subparsers(dest="command")
+
+    p_start = sub.add_parser("start")
+    p_start.add_argument("--port",       type=int,   default=None)
+    p_start.add_argument("--no-browser", action="store_true")
+    p_start.add_argument("--budget",     type=float, default=None)
+
+    sub.add_parser("status")
+
+    p_exp = sub.add_parser("export")
+    p_exp.add_argument("--format", choices=["csv", "json"], default="csv")
+    p_exp.add_argument("--days",   type=int, default=30)
+
+    p_seed = sub.add_parser("seed")
+    p_seed.add_argument("--days",  type=int, default=30)
+    p_seed.add_argument("--clean", action="store_true")
+
+    sub.add_parser("config")
+
+    p_lic = sub.add_parser("license")
+    p_lic.add_argument("--key", type=str, default=None)
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        args.command    = "start"
+        args.port       = None
+        args.no_browser = False
+        args.budget     = None
+
+    {
+        "start":   cmd_start,
+        "status":  cmd_status,
+        "export":  cmd_export,
+        "seed":    cmd_seed,
+        "config":  cmd_config,
+        "license": cmd_license,
+    }[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

tokenwatch-0.2.0/tokenwatch/config.py

@@ -0,0 +1,50 @@
+"""
+config.py — User configuration for TokenWatch.
+
+Settings are stored in ~/.claude/tokenwatch_config.json
+Edit the file directly, or use the /api/config endpoint.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CONFIG_FILE = Path.home() / ".claude" / "tokenwatch_config.json"
+
+DEFAULTS: dict = {
+    "daily_budget":       10.00,   # USD — alert thresholds are % of this
+    "alert_at_pct":       [80, 100],  # fire desktop notification at these %
+    "history_days":       30,      # how many days of sessions to keep in memory
+    "port":               7842,
+    "open_browser":       True,    # open browser automatically on `tokenwatch` start
+    "digest_email":       "",      # leave blank to disable weekly email digest
+}
+
+
+def load() -> dict:
+    try:
+        if CONFIG_FILE.exists():
+            stored = json.loads(CONFIG_FILE.read_text())
+            # Merge with defaults so new keys are always present
+            return {**DEFAULTS, **stored}
+    except Exception as e:
+        logger.warning(f"Could not read config: {e}")
+    return dict(DEFAULTS)
+
+
+def save(cfg: dict) -> None:
+    try:
+        CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+        logger.info(f"Config saved to {CONFIG_FILE}")
+    except Exception as e:
+        logger.warning(f"Could not save config: {e}")
+
+
+def update(key: str, value) -> dict:
+    cfg = load()
+    cfg[key] = value
+    save(cfg)
+    return cfg