burndown 0.1.0__tar.gz

burndown-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} · py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # Zero runtime deps — only pytest is needed to run the suite.
+      - run: python -m pip install --upgrade pip pytest
+      - run: python -m pytest tests/ -q
+      # Smoke: the CLI must import + run on every OS (no logs in CI is fine).
+      - run: python -m burndown config

burndown-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+
+# burndown's own generated artifacts (never commit a usage report)
+burndown-report.html
+*-report.html
+
+# internal strategy / session-context doc (never ship)
+BURNDOWN_STATUS.md
+
+# os
+.DS_Store

burndown-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — unreleased
+Initial vertical slice.
+- Read Claude Code usage logs (`~/.claude/projects/**/*.jsonl`), privacy-safe and
+  read-only; de-dup by message uuid; skip `<synthetic>`.
+- Configurable per-model pricing (estimated defaults) + token-budget mode.
+- Period aggregation (monthly/weekly/daily) with by-project / by-model / by-day
+  breakdowns and a 24h/7d recent-pace.
+- Forecast: burn rate, runway (days-to-zero at recent pace), projected period
+  total, over-budget detection.
+- CLI: `status` · `watch` · `budget` · `check` · `report` (HTML) · `config` · `currency`.
+- Dual-currency display (USD + a configurable secondary currency, e.g. INR) via a
+  static FX rate — no live fetch, zero-network preserved (ADR-007).
+- **Credit-pool guardian:** programmatic vs interactive split via the `entrypoint`
+  field; `scope` config + `burndown scope programmatic` make the headline + runway
+  meter just the June-2026 credit pool (ADR-009). Split always shown for context.
+- **Local web dashboard:** `burndown serve` → auto-refreshing page on 127.0.0.1
+  (loopback only, self-contained, no external resources; ADR-010).
+- **Cross-platform:** macOS/Linux/Windows log-dir auto-discovery, `%APPDATA%`
+  config on Windows, Windows ANSI enable, `\`-safe project names; CI matrix across
+  all three OSes × Python 3.11–3.13 (ADR-011).
+- Test suite: 23 tests across parser/pricing/aggregate/forecast/currency/scope/
+  dashboard, incl. a structural content-blindness assertion. Zero runtime deps.
+- Full decision log (8 ADRs) + threat model.

burndown-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryaman Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

burndown-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: burndown
+Version: 0.1.0
+Summary: A local, real-time cockpit for your Claude credit burn — burn rate, runway forecast, and budget alerts. Zero dependencies, nothing leaves your machine.
+Project-URL: Homepage, https://github.com/aryasgit/burndown
+Project-URL: Source, https://github.com/aryasgit/burndown
+Project-URL: Issues, https://github.com/aryasgit/burndown/issues
+Project-URL: Changelog, https://github.com/aryasgit/burndown/blob/main/CHANGELOG.md
+Author-email: Aryaman Gupta <rayman3304@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,budget,claude,claude-code,cli,cost,credits,local-first,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Burndown
+
+**A local, real-time cockpit for your Claude credit burn.**
+Burn rate · runway forecast · budget alerts — so you see "I'll run dry in 3 days" *before* it happens, not after.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-000.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-000.svg)](https://python.org)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-0-000.svg)]()
+[![100%25 local](https://img.shields.io/badge/runs-100%25%20local-000.svg)]()
+
+</div>
+
+---
+
+Anthropic split programmatic Claude usage into a **separate monthly credit pool**
+that can run out mid-month. The existing tools show you what you *already* spent —
+a bank statement, after the fact. Burndown is the **fuel gauge**: how fast you're
+burning right now, when you'll hit zero, and a check that fires before you overspend.
+
+It reads the usage logs Claude Code already writes on your machine. **Nothing
+leaves your computer** — zero dependencies, no network, read-only on your logs,
+and it never touches your prompts or code (see [SECURITY.md](docs/SECURITY.md)).
+
+## Quickstart
+
+```bash
+pipx install git+https://github.com/aryasgit/burndown.git   # works today (PyPI: `pipx install burndown` — soon)
+burndown                     # snapshot of this period
+burndown budget 100          # set your monthly credit-pool budget → get a runway
+burndown scope programmatic  # guardian mode: meter just the credit pool
+burndown currency INR        # show INR next to USD (static rate, no live fetch)
+burndown watch               # live terminal dashboard …
+burndown serve               # … or a web dashboard at http://127.0.0.1:8787
+```
+
+No install? From a clone: `python -m burndown` (needs Python 3.11+, nothing else).
+
+```
+  BURNDOWN   monthly period · resets Jul 01
+
+  $41.80 / $100.00   ███████████░░░░░░░░░░░░░░░░░  42%
+
+  burn rate   $6.10/day   (last 24h)      avg $3.20/day
+  runway      9.6 days  (Jun 22)   ✓ lasts the period
+  projected   $89.40 by reset
+
+  top projects
+    memcon                     $22.10
+    burndown                   $11.40
+    barq-firmware              $8.30
+
+  last 14d    ▂▁▃▅▂▇█▄▃▂▅▆▃▄
+
+  1,204 billable msgs · 38,902,114 tokens · 100% local, nothing sent anywhere
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `burndown` / `burndown status` | one-shot snapshot |
+| `burndown watch [--interval 5]` | live dashboard, re-reads logs every few seconds |
+| `burndown budget <amount> [--tokens] [--reset-day N]` | set the budget runway is measured against (dollars, or `--tokens` to skip pricing) |
+| `burndown scope programmatic` | **guardian mode** — meter just the June-2026 credit pool (programmatic usage); `all` / `interactive` also available |
+| `burndown currency INR [--rate R]` | show a second currency next to USD (static rate, no live fetch) |
+| `burndown check` | exit `0` ok · `1` projected-over · `2` over — wire it into your own pre-run hook / CI |
+| `burndown report [--html out.html]` | self-contained local HTML report (opens from `file://`, no server) |
+| `burndown serve [--port 8787]` | live **web dashboard** on `127.0.0.1` — local only, auto-refreshing (nice if you don't live in a terminal) |
+| `burndown config` | show config + verify which logs are being read |
+
+## How it works
+
+Claude Code logs every assistant message to `~/.claude/projects/**/*.jsonl` with
+a `usage` block (input / output / cache-write / cache-read tokens). Burndown
+reads those numbers (only those — never the message text), prices them with a
+configurable per-model table, rolls them into your current billing period,
+computes burn rate from the **last 24 hours**, and projects when you'll hit your
+budget.
+
+## Honest limitations
+
+- **Pricing is estimated and configurable.** Default per-model rates are
+  best-effort; correct them in `~/.config/burndown/config.toml` (`burndown
+  config` shows the active table). The burn-rate/runway math is exact regardless
+  — prices only scale the dollar figure. Prefer not to trust a dollar estimate?
+  `burndown budget <N> --tokens` forecasts in raw tokens.
+- It reads **local Claude Code logs**. If your usage doesn't write those logs
+  (e.g. a flow that doesn't log locally), Burndown can't see it yet.
+- The "budget stop" is a **check you act on**, not an auto-kill (on purpose — see
+  [ADR-005](docs/DECISIONS.md)).
+
+## Trust
+
+Zero dependencies · no outbound network (the optional dashboard is loopback-only) · read-only · content-blind · cross-platform (macOS/Linux/Windows) · MIT.
+Verify it yourself in one line:
+```bash
+grep -REn "urllib|httpx|requests|telemetry|analytics|0\.0\.0\.0|socket\.socket|create_connection|\.connect\(" burndown/   # → nothing (the only socket binds 127.0.0.1)
+```
+
+Decisions are logged in [docs/DECISIONS.md](docs/DECISIONS.md); the threat model
+is in [docs/SECURITY.md](docs/SECURITY.md).

burndown-0.1.0/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+
+# Burndown
+
+**A local, real-time cockpit for your Claude credit burn.**
+Burn rate · runway forecast · budget alerts — so you see "I'll run dry in 3 days" *before* it happens, not after.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-000.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-000.svg)](https://python.org)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-0-000.svg)]()
+[![100%25 local](https://img.shields.io/badge/runs-100%25%20local-000.svg)]()
+
+</div>
+
+---
+
+Anthropic split programmatic Claude usage into a **separate monthly credit pool**
+that can run out mid-month. The existing tools show you what you *already* spent —
+a bank statement, after the fact. Burndown is the **fuel gauge**: how fast you're
+burning right now, when you'll hit zero, and a check that fires before you overspend.
+
+It reads the usage logs Claude Code already writes on your machine. **Nothing
+leaves your computer** — zero dependencies, no network, read-only on your logs,
+and it never touches your prompts or code (see [SECURITY.md](docs/SECURITY.md)).
+
+## Quickstart
+
+```bash
+pipx install git+https://github.com/aryasgit/burndown.git   # works today (PyPI: `pipx install burndown` — soon)
+burndown                     # snapshot of this period
+burndown budget 100          # set your monthly credit-pool budget → get a runway
+burndown scope programmatic  # guardian mode: meter just the credit pool
+burndown currency INR        # show INR next to USD (static rate, no live fetch)
+burndown watch               # live terminal dashboard …
+burndown serve               # … or a web dashboard at http://127.0.0.1:8787
+```
+
+No install? From a clone: `python -m burndown` (needs Python 3.11+, nothing else).
+
+```
+  BURNDOWN   monthly period · resets Jul 01
+
+  $41.80 / $100.00   ███████████░░░░░░░░░░░░░░░░░  42%
+
+  burn rate   $6.10/day   (last 24h)      avg $3.20/day
+  runway      9.6 days  (Jun 22)   ✓ lasts the period
+  projected   $89.40 by reset
+
+  top projects
+    memcon                     $22.10
+    burndown                   $11.40
+    barq-firmware              $8.30
+
+  last 14d    ▂▁▃▅▂▇█▄▃▂▅▆▃▄
+
+  1,204 billable msgs · 38,902,114 tokens · 100% local, nothing sent anywhere
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `burndown` / `burndown status` | one-shot snapshot |
+| `burndown watch [--interval 5]` | live dashboard, re-reads logs every few seconds |
+| `burndown budget <amount> [--tokens] [--reset-day N]` | set the budget runway is measured against (dollars, or `--tokens` to skip pricing) |
+| `burndown scope programmatic` | **guardian mode** — meter just the June-2026 credit pool (programmatic usage); `all` / `interactive` also available |
+| `burndown currency INR [--rate R]` | show a second currency next to USD (static rate, no live fetch) |
+| `burndown check` | exit `0` ok · `1` projected-over · `2` over — wire it into your own pre-run hook / CI |
+| `burndown report [--html out.html]` | self-contained local HTML report (opens from `file://`, no server) |
+| `burndown serve [--port 8787]` | live **web dashboard** on `127.0.0.1` — local only, auto-refreshing (nice if you don't live in a terminal) |
+| `burndown config` | show config + verify which logs are being read |
+
+## How it works
+
+Claude Code logs every assistant message to `~/.claude/projects/**/*.jsonl` with
+a `usage` block (input / output / cache-write / cache-read tokens). Burndown
+reads those numbers (only those — never the message text), prices them with a
+configurable per-model table, rolls them into your current billing period,
+computes burn rate from the **last 24 hours**, and projects when you'll hit your
+budget.
+
+## Honest limitations
+
+- **Pricing is estimated and configurable.** Default per-model rates are
+  best-effort; correct them in `~/.config/burndown/config.toml` (`burndown
+  config` shows the active table). The burn-rate/runway math is exact regardless
+  — prices only scale the dollar figure. Prefer not to trust a dollar estimate?
+  `burndown budget <N> --tokens` forecasts in raw tokens.
+- It reads **local Claude Code logs**. If your usage doesn't write those logs
+  (e.g. a flow that doesn't log locally), Burndown can't see it yet.
+- The "budget stop" is a **check you act on**, not an auto-kill (on purpose — see
+  [ADR-005](docs/DECISIONS.md)).
+
+## Trust
+
+Zero dependencies · no outbound network (the optional dashboard is loopback-only) · read-only · content-blind · cross-platform (macOS/Linux/Windows) · MIT.
+Verify it yourself in one line:
+```bash
+grep -REn "urllib|httpx|requests|telemetry|analytics|0\.0\.0\.0|socket\.socket|create_connection|\.connect\(" burndown/   # → nothing (the only socket binds 127.0.0.1)
+```
+
+Decisions are logged in [docs/DECISIONS.md](docs/DECISIONS.md); the threat model
+is in [docs/SECURITY.md](docs/SECURITY.md).

burndown-0.1.0/burndown/__init__.py

@@ -0,0 +1,6 @@
+"""Burndown — a local, real-time cockpit for your Claude credit burn.
+
+Zero runtime dependencies. 100% local. Read-only on your logs. Content-blind.
+Nothing this package does opens a network connection.
+"""
+__version__ = "0.1.0"

burndown-0.1.0/burndown/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

burndown-0.1.0/burndown/aggregate.py

@@ -0,0 +1,92 @@
+"""
+burndown/aggregate.py — roll a stream of Events into a period Snapshot.
+Pure functions, no I/O — unit-tested offline.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+from .pricing import cost_usd
+
+
+def period_window(period: str, reset_day: int, now: datetime) -> tuple[datetime, datetime]:
+    """[start, end) of the billing window `now` falls in."""
+    now = now.astimezone(timezone.utc)
+    if period == "daily":
+        start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return start, start + timedelta(days=1)
+    if period == "weekly":
+        start = (now - timedelta(days=now.weekday())).replace(
+            hour=0, minute=0, second=0, microsecond=0)
+        return start, start + timedelta(weeks=1)
+    # monthly, anchored on reset_day
+    rd = max(1, min(28, reset_day))
+    midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    if now.day >= rd:
+        start = midnight.replace(day=rd)
+    else:
+        prev_last = midnight.replace(day=1) - timedelta(days=1)
+        start = prev_last.replace(day=rd)
+    end = start.replace(year=start.year + 1, month=1) if start.month == 12 \
+        else start.replace(month=start.month + 1)
+    return start, end
+
+
+@dataclass
+class Snapshot:
+    now: datetime
+    period: str
+    period_start: datetime
+    period_end: datetime
+    spent_usd: float = 0.0
+    tokens: int = 0
+    events: int = 0
+    by_project: dict = field(default_factory=dict)   # name -> usd
+    by_model: dict = field(default_factory=dict)      # model -> usd
+    by_day: dict = field(default_factory=dict)        # 'YYYY-MM-DD' -> usd
+    cost_last_24h: float = 0.0
+    cost_last_7d: float = 0.0
+    spent_programmatic: float = 0.0   # period $ split — always tracked, for the breakdown line
+    spent_interactive: float = 0.0
+
+
+def build_snapshot(events, cfg, now: datetime | None = None, scope: str = "all") -> Snapshot:
+    """Roll events into a period snapshot.
+
+    `scope` filters what the headline (spent / burn / runway) is about:
+      'all' — every event; 'programmatic' — credit-pool usage only;
+      'interactive' — app usage only. The programmatic/interactive period split is
+      ALWAYS tracked (for the breakdown line) regardless of scope.
+    """
+    now = (now or datetime.now(timezone.utc)).astimezone(timezone.utc)
+    start, end = period_window(cfg.period, cfg.reset_day, now)
+    snap = Snapshot(now=now, period=cfg.period, period_start=start, period_end=end)
+    t24, t7 = now - timedelta(hours=24), now - timedelta(days=7)
+
+    def in_scope(e) -> bool:
+        return scope == "all" or e.programmatic == (scope == "programmatic")
+
+    for e in events:
+        c = cost_usd(e.model, e.input, e.output, e.cache_write, e.cache_read, cfg.pricing)
+        if in_scope(e):
+            if t24 <= e.ts <= now:
+                snap.cost_last_24h += c
+            if t7 <= e.ts <= now:
+                snap.cost_last_7d += c
+        if not (start <= e.ts < end):
+            continue
+        if e.programmatic:                 # period split — always, for the breakdown
+            snap.spent_programmatic += c
+        else:
+            snap.spent_interactive += c
+        if not in_scope(e):                # headline rollup respects the scope
+            continue
+        snap.spent_usd += c
+        snap.tokens += e.total_tokens
+        snap.events += 1
+        snap.by_project[e.project] = snap.by_project.get(e.project, 0.0) + c
+        snap.by_model[e.model] = snap.by_model.get(e.model, 0.0) + c
+        d = e.ts.date().isoformat()
+        snap.by_day[d] = snap.by_day.get(d, 0.0) + c
+    return snap

burndown-0.1.0/burndown/cli.py

@@ -0,0 +1,184 @@
+"""
+burndown/cli.py — command-line entry. Subcommands:
+
+  status   one-shot snapshot (default)
+  watch    live terminal dashboard (re-reads logs every few seconds)
+  budget   set/show the budget the forecast is measured against
+  report   write a self-contained local HTML report
+  check    exit non-zero if over / projected-over budget (for your own hooks)
+  config   show config + verify which logs are being read
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+
+def _enable_windows_ansi() -> None:
+    """Turn on ANSI/VT processing on Windows 10+ so colors render in the terminal."""
+    if os.name != "nt":
+        return
+    try:
+        import ctypes
+        k = ctypes.windll.kernel32
+        k.SetConsoleMode(k.GetStdHandle(-11), 7)  # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+    except Exception:
+        pass
+
+from . import config as cfgmod
+from . import report
+from .aggregate import build_snapshot
+from .forecast import build_forecast
+from .logs import find_log_files, iter_events
+from .money import KNOWN_FX, money
+
+
+def _snapshot(cfg):
+    snap = build_snapshot(iter_events(cfg.log_dirs), cfg, scope=cfg.scope)
+    return snap, build_forecast(snap, cfg)
+
+
+def cmd_status(cfg, args):
+    snap, fc = _snapshot(cfg)
+    print(report.render_status(snap, fc, cfg))
+
+
+def cmd_watch(cfg, args):
+    interval = max(2, getattr(args, "interval", 5))
+    try:
+        while True:
+            cfg = cfgmod.load()
+            snap, fc = _snapshot(cfg)
+            sys.stdout.write("\033[2J\033[H")   # clear + home
+            print(report.render_status(snap, fc, cfg))
+            print(report.c(f"\n  refreshing every {interval}s · ctrl-c to quit", "gray"))
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        print()
+
+
+def cmd_budget(cfg, args):
+    if args.amount is None:
+        val = "not set" if cfg.budget is None else money(cfg.budget, cfg)
+        print(f"budget: {val} per {cfg.period} (resets day {cfg.reset_day})")
+        return
+    cfg.budget = float(args.amount)
+    cfg.budget_unit = "tokens" if args.tokens else "usd"
+    if args.period:
+        cfg.period = args.period
+    if args.reset_day:
+        cfg.reset_day = max(1, min(28, args.reset_day))
+    path = cfgmod.save(cfg)
+    print(f"saved → {path}\n")
+    cmd_status(cfgmod.load(), args)
+
+
+def cmd_currency(cfg, args):
+    if not args.code:
+        sec = f"{cfg.currency2} @ {cfg.fx_rate}" if cfg.currency2 else "USD only"
+        print(f"secondary currency: {sec}")
+        print(f"known codes: {', '.join(KNOWN_FX)}")
+        return
+    code = args.code.upper()
+    sym, default_rate = KNOWN_FX.get(code, (code + " ", 0.0))
+    cfg.currency2 = code
+    cfg.currency2_symbol = args.symbol or sym
+    cfg.fx_rate = args.rate if args.rate else default_rate
+    if not cfg.fx_rate:
+        print(f"unknown code {code} — pass a rate: `burndown currency {code} --rate <USD->{code}>`")
+        return
+    path = cfgmod.save(cfg)
+    print(f"saved → {path}  (showing USD + {code} @ {cfg.fx_rate}; static rate, no live fetch)\n")
+    cmd_status(cfgmod.load(), args)
+
+
+def cmd_scope(cfg, args):
+    if not args.value:
+        print(f"scope: {cfg.scope}   (all | programmatic = credit pool | interactive)")
+        return
+    cfg.scope = args.value
+    path = cfgmod.save(cfg)
+    note = " — metering your credit-pool usage" if args.value == "programmatic" else ""
+    print(f"saved → {path}{note}\n")
+    cmd_status(cfgmod.load(), args)
+
+
+def cmd_config(cfg, args):
+    files = find_log_files(cfg.log_dirs)
+    pricing = "custom (config)" if cfg.pricing else "defaults — estimated, override in config"
+    print(f"config file : {cfgmod.config_path()}")
+    print(f"log dirs    : {', '.join(cfg.log_dirs)}")
+    print(f"log files   : {len(files)} *.jsonl found")
+    print(f"budget      : {cfg.budget if cfg.budget is not None else 'not set'} {cfg.budget_unit}")
+    print(f"period      : {cfg.period} (reset day {cfg.reset_day})")
+    print(f"pricing     : {pricing}")
+    print("network     : none — burndown never opens a connection")
+
+
+def cmd_report(cfg, args):
+    snap, fc = _snapshot(cfg)
+    out = args.html or "burndown-report.html"
+    with open(out, "w") as f:
+        f.write(report.render_html(snap, fc, cfg))
+    print(f"wrote {out}")
+
+
+def cmd_serve(cfg, args):
+    from . import serve as serve_mod
+    serve_mod.serve(port=args.port, open_browser=not args.no_open)
+
+
+def cmd_check(cfg, args):
+    snap, fc = _snapshot(cfg)
+    if fc.budget is None:
+        print("no budget set — nothing to check")
+        sys.exit(0)
+    if fc.spent >= fc.budget:
+        print(f"OVER budget: {money(fc.spent, cfg)} of {money(fc.budget, cfg)}")
+        sys.exit(2)
+    if fc.will_exceed:
+        print(f"projected to exceed before reset ({money(fc.projected_period_total, cfg)})")
+        sys.exit(1)
+    print(f"within budget ({fc.pct_used:.0f}% used)")
+    sys.exit(0)
+
+
+def main(argv=None):
+    _enable_windows_ansi()
+    p = argparse.ArgumentParser(
+        prog="burndown",
+        description="A local, real-time cockpit for your Claude credit burn. "
+                    "Zero dependencies, 100%% local, nothing leaves your machine.")
+    sub = p.add_subparsers(dest="cmd")
+    sub.add_parser("status", help="one-shot snapshot (default)")
+    w = sub.add_parser("watch", help="live dashboard")
+    w.add_argument("--interval", type=int, default=5)
+    b = sub.add_parser("budget", help="set/show your budget")
+    b.add_argument("amount", nargs="?", type=float)
+    b.add_argument("--tokens", action="store_true", help="budget in tokens, not dollars")
+    b.add_argument("--period", choices=["monthly", "weekly", "daily"])
+    b.add_argument("--reset-day", dest="reset_day", type=int, help="day-of-month the pool resets")
+    sub.add_parser("config", help="show config + which logs are read")
+    sc = sub.add_parser("scope", help="meter all usage, or just the credit pool")
+    sc.add_argument("value", nargs="?", choices=["all", "programmatic", "interactive"])
+    cu = sub.add_parser("currency", help="show USD + a second currency (e.g. INR)")
+    cu.add_argument("code", nargs="?", help="currency code, e.g. INR")
+    cu.add_argument("--rate", type=float, help="USD -> code conversion (static, no live fetch)")
+    cu.add_argument("--symbol", help="currency symbol, e.g. ₹")
+    r = sub.add_parser("report", help="write a self-contained HTML report")
+    r.add_argument("--html", help="output path (default burndown-report.html)")
+    sv = sub.add_parser("serve", help="open a local web dashboard (127.0.0.1 only)")
+    sv.add_argument("--port", type=int, default=8787)
+    sv.add_argument("--no-open", action="store_true", help="don't auto-open the browser")
+    sub.add_parser("check", help="exit non-zero if over/projected-over budget")
+
+    args = p.parse_args(argv)
+    cfg = cfgmod.load()
+    dispatch = {
+        "status": cmd_status, "watch": cmd_watch, "budget": cmd_budget,
+        "config": cmd_config, "scope": cmd_scope, "currency": cmd_currency,
+        "report": cmd_report, "serve": cmd_serve, "check": cmd_check,
+    }
+    dispatch[args.cmd or "status"](cfg, args)