burnmeter 0.3.8__py3-none-any.whl

burnmeter/__init__.py

@@ -0,0 +1,6 @@
+"""burnmeter — Local Claude Code token usage meter.
+
+Privacy: Reads only ~/.claude/projects/. No network calls except to fetch
+Chart.js from CDN in the browser. The Python server itself is fully offline.
+"""
+__version__ = "0.3.8"

burnmeter/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+import sys
+sys.exit(main())

burnmeter/_proc.py

@@ -0,0 +1,13 @@
+"""Process helper.
+
+When Burnmeter runs windowless (system tray / pythonw — no console of its own),
+any console child process it spawns (git, the build worker, taskkill, powershell)
+would otherwise POP its own console window for the instant it runs. Across a
+running session that shows up as cmd windows "flashing" every cache rebuild.
+Passing CREATE_NO_WINDOW suppresses that window. On non-Windows it's 0 (no-op),
+so call sites can pass `creationflags=NO_WINDOW` unconditionally.
+"""
+import sys
+
+# CREATE_NO_WINDOW (0x08000000) on Windows; 0 elsewhere.
+NO_WINDOW = 0x08000000 if sys.platform.startswith("win") else 0

burnmeter/_worker.py

@@ -0,0 +1,141 @@
+"""Short-lived build worker — bounds the long-running server's RSS.
+
+The server spawns this as a subprocess, sends a JSON config on stdin, and reads
+the built report JSON from stdout. The worker loads ~half-a-million records,
+builds the report (transiently spiking to ~800MB), prints the JSON, then EXITS
+— so the OS reclaims that memory immediately. The long-running server process
+only ever holds the small report JSON (~0.5MB), never the raw records.
+
+This is a zero-logic-change RAM fix: the exact same load_records / build_report
+run, just in a process that dies after each build. No streaming-aggregate
+rewrite, no risk of subtly wrong numbers.
+
+Usage: `python3 -m burnmeter._worker` then write config JSON to stdin:
+  {"source":"codex","projects_dir":"...","extra_roots":[...],
+   "codex_dir":"...","codex_extra_roots":[...],"plan":null}
+Prints report JSON to stdout. Non-zero exit on error.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+
+
+def _exit_with_parent(poll: float = 2.0) -> None:
+    """Exit when the server that spawned this worker dies.
+
+    A killed or crashed server left its worker running until the build ended:
+    1.2-1.8 GB for minutes, and a restarted server started a second one. The
+    server passes its pid; the worker removes its config and report files, which
+    no one will read or delete now, and exits. Runs as a daemon thread.
+    """
+    ppid = int(os.environ.get("BURNMETER_WORKER_PARENT") or os.getppid())
+    if sys.platform.startswith("win"):
+        import ctypes
+        k32 = ctypes.WinDLL("kernel32")
+        k32.OpenProcess.restype = ctypes.c_void_p
+        k32.OpenProcess.argtypes = [ctypes.c_uint32, ctypes.c_int, ctypes.c_uint32]
+        k32.WaitForSingleObject.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+        h = k32.OpenProcess(0x00100000, False, ppid)    # SYNCHRONIZE; None: already gone
+        if h:
+            k32.WaitForSingleObject(h, 0xFFFFFFFF)       # INFINITE
+    else:
+        while os.getppid() == ppid:                      # re-parented once it dies
+            time.sleep(poll)
+    for var in ("BURNMETER_WORKER_IN", "BURNMETER_WORKER_OUT", "BURNMETER_WORKER_PROGRESS"):
+        try:
+            os.unlink(os.environ[var])
+        except (KeyError, OSError):
+            pass
+    os._exit(3)
+
+
+def _progress_writer(path):
+    """A callback that keeps the read's progress in `path` for the server's loading
+    screen: the latest counts, merged and written whole (temp file, then rename), so
+    the server never reads half a file. None when no path was given."""
+    if not path:
+        return None
+    state = {"phase": "reading", "started_at": time.time()}
+
+    def write(update: dict) -> None:
+        state.update(update)
+        tmp = f"{path}.tmp"
+        try:
+            Path(tmp).write_text(json.dumps(state), encoding="utf-8")
+            os.replace(tmp, path)
+        except OSError:
+            pass
+    write({})
+    return write
+
+
+def main() -> int:
+    threading.Thread(target=_exit_with_parent, name="parent-watch", daemon=True).start()
+    # Config in / report out go through FILES (env vars) when set — a frozen
+    # --windowed (no-console) process has no usable stdin/stdout, so writing the
+    # report to stdout raised OSError [Errno 22]. Fall back to stdin/stdout for
+    # plain `python -m burnmeter._worker` use.
+    src = os.environ.get("BURNMETER_WORKER_IN")
+    raw = Path(src).read_text(encoding="utf-8") if src else (sys.stdin.read() or "{}")
+    try:
+        cfg = json.loads(raw or "{}")
+    except json.JSONDecodeError as e:
+        try:
+            sys.stderr.write(f"[worker] bad config: {e}\n")
+        except Exception:
+            pass
+        return 2
+
+    source = cfg.get("source", "claude")
+    plan = cfg.get("plan")
+    progress = _progress_writer(os.environ.get("BURNMETER_WORKER_PROGRESS"))
+
+    from .analytics import build_report
+
+    if source == "codex":
+        from .codex_parser import load_codex_records, CODEX_SESSIONS_DIR
+        root = Path(cfg["codex_dir"]) if cfg.get("codex_dir") else CODEX_SESSIONS_DIR
+        extra = [Path(p) for p in (cfg.get("codex_extra_roots") or [])]
+        records, stats, intents = load_codex_records(
+            root, extra_roots=extra, since_days=int(cfg.get("codex_since_days", 90)),
+            progress=progress)
+        errors = []
+    else:
+        from datetime import datetime, timedelta, timezone
+        from .parser import load_records, CLAUDE_PROJECTS_DIR
+        root = Path(cfg["projects_dir"]) if cfg.get("projects_dir") else CLAUDE_PROJECTS_DIR
+        extra = [Path(p) for p in (cfg.get("extra_roots") or [])]
+        # since_hours: the quick report a fresh install shows while its first full
+        # read runs (only the recent logs, no parse cache).
+        since = (datetime.now(timezone.utc) - timedelta(hours=float(cfg["since_hours"]))
+                 if cfg.get("since_hours") else None)
+        records, stats, intents, errors = load_records(root, extra_roots=extra, since=since,
+                                                       progress=progress)
+
+    if progress:
+        progress({"phase": "building"})
+    report = build_report(records, plan=plan, user_intents=intents,
+                          error_events=errors, source=source)
+    report["_meta"] = {**stats, "source": source}
+    if source == "codex" and stats.get("rate_limits"):
+        report["codex_rate_limits"] = stats["rate_limits"]
+
+    # Release before serializing (records no longer needed).
+    records = None
+    out = json.dumps(report, default=str)
+    dest = os.environ.get("BURNMETER_WORKER_OUT")
+    if dest:
+        Path(dest).write_text(out, encoding="utf-8")
+    else:
+        sys.stdout.write(out)
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

burnmeter/alerts.py

@@ -0,0 +1,223 @@
+"""Burnmeter — local, privacy-preserving pre-limit alerts.
+
+Runs ENTIRELY on the user's machine: the local `burnmeter` process evaluates the
+same thresholds the dashboard shows and pushes a notification to the user's OWN
+webhook / Slack / email when a binding constraint is about to be hit. Nothing is
+ever sent to a Burnmeter-operated server — the local-first promise holds (no
+phone-home). This is what lets an alert reach you when the dashboard tab is
+closed: the local server keeps evaluating in a background thread.
+
+Threshold logic is a faithful port of dashboard.js `alertLevelOf`, so the
+terminal/server alerts and the in-browser toast never disagree.
+
+Config: ~/.config/burnmeter/alerts.json (chmod 600 — may hold SMTP creds).
+Senders use only the Python standard library (urllib, smtplib).
+
+Example alerts.json:
+    {
+      "enabled": true,
+      "sources": ["claude", "codex"],
+      "destinations": {
+        "webhook_url": "https://example.com/hook",
+        "slack_webhook_url": "https://hooks.slack.com/services/...",
+        "email": {"host": "smtp.gmail.com", "port": 587, "tls": true,
+                   "username": "you@gmail.com", "password": "app-password",
+                   "from": "you@gmail.com", "to": "you@gmail.com"}
+      }
+    }
+"""
+from __future__ import annotations
+
+import json
+import smtplib
+import ssl
+import urllib.request
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Optional
+
+CONFIG_PATH = Path.home() / ".config" / "burnmeter" / "alerts.json"
+
+# Thresholds — keep in sync with dashboard.js alertLevelOf.
+RATE_LIMIT_WARN = 85     # % of account rate-limit (Codex)
+RATE_LIMIT_CRIT = 95     # %
+BURN_HEAVY_MULT = 1.6    # Claude: warn when burn-rate >= 'heavy' zone * this
+WEEK_OVER_P95_MULT = 1.2  # budget pace: warn when this week's spend > heaviest week * this
+
+LEVEL_NAMES = {0: "ok", 2: "warn", 3: "crit"}
+
+
+# ---------- config ----------
+def load_config(path: Path = CONFIG_PATH) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(cfg: dict, path: Path = CONFIG_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+    try:
+        path.chmod(0o600)   # may contain an SMTP password
+    except OSError:
+        pass
+
+
+def is_enabled(cfg: Optional[dict] = None) -> bool:
+    c = cfg if cfg is not None else load_config()
+    return bool(c.get("enabled")) and bool(c.get("destinations"))
+
+
+def _money(n) -> str:
+    try:
+        return f"${float(n):,.0f}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+# ---------- evaluate (faithful port of dashboard.js alertLevelOf) ----------
+def evaluate(report: dict, source: str) -> tuple[int, str]:
+    """Return (level, message). level: 0 safe, 2 warn, 3 critical.
+
+    - Codex (has account rate-limits): max(primary, secondary) used_percent —
+      >=95 critical, >=85 warning.
+    - Claude (no account limit): burn-rate vs the 'heavy' reference zone —
+      >= heavy * 1.6 warning.
+    """
+    level, msg = 0, ""
+    if source == "codex":
+        rls = report.get("codex_rate_limits") or {}
+        if rls:
+            dev = rls.get("mac") or next(iter(rls.values()), {}) or {}
+            primary = (dev.get("primary") or {}).get("used_percent") or 0
+            secondary = (dev.get("secondary") or {}).get("used_percent") or 0
+            bp = max(primary, secondary)
+            if bp >= RATE_LIMIT_CRIT:
+                level, msg = 3, f"\U0001f534 Codex limit at {round(bp)}% — throttle is IMMINENT"
+            elif bp >= RATE_LIMIT_WARN:
+                level, msg = 2, f"\U0001f7e0 Codex limit at {round(bp)}% — approaching the wall"
+    else:
+        # claude — no account limit, so we warn on excessive burn rate
+        fc = report.get("forecast") or {}
+        zones = report.get("burn_rate_zones") or {}
+        by_hours = fc.get("burn_rates_by_hours") or {}
+        rate = by_hours.get("2")
+        if rate is None:
+            rate = fc.get("burn_rate_per_hour_recent") or 0
+        heavy = zones.get("heavy")
+        if heavy and rate >= heavy * BURN_HEAVY_MULT:
+            level, msg = 2, f"\U0001f7e0 Burn rate is very high: {_money(rate)}/hr"
+
+    # Budget pace (any source) — the math was ALWAYS computed by analytics (weekly_cap +
+    # forecast.month) but never read here; this is the "you're on pace to overspend" alert.
+    # Fire only vs the user's OWN history (p95 of their heaviest week) — no invented budgets.
+    wc = report.get("weekly_cap") or {}
+    week = wc.get("rolling_7d_cost") or 0
+    p95 = wc.get("historical_7d_p95") or 0
+    if p95 > 0 and week >= p95 * WEEK_OVER_P95_MULT:
+        eom = ((report.get("forecast") or {}).get("month") or {}).get("projected_eom")
+        pace = (f"\U0001f4c8 Spending pace: {_money(week)} this week — "
+                f"{round(week / p95 * 100 - 100)}% above your heaviest week ({_money(p95)})")
+        if eom:
+            pace += f". On pace for {_money(eom)} this month."
+        if 2 > level:
+            level, msg = 2, pace
+    return level, msg
+
+
+# ---------- senders (stdlib only) ----------
+def send_webhook(url: str, payload: dict, timeout: int = 10) -> None:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, method="POST",
+        headers={"Content-Type": "application/json", "User-Agent": "burnmeter-alerts"},
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        r.read()
+
+
+def send_slack(url: str, text: str, timeout: int = 10) -> None:
+    # Slack Incoming Webhooks accept {"text": ...}.
+    send_webhook(url, {"text": text}, timeout=timeout)
+
+
+def send_email(smtp: dict, subject: str, body: str) -> None:
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = smtp.get("from") or smtp.get("username") or "burnmeter@localhost"
+    msg["To"] = smtp["to"]
+    msg.set_content(body)
+    host = smtp.get("host", "localhost")
+    port = int(smtp.get("port", 587))
+    with smtplib.SMTP(host, port, timeout=20) as s:
+        if smtp.get("tls", True):
+            s.starttls(context=ssl.create_default_context())
+        if smtp.get("username"):
+            s.login(smtp["username"], smtp.get("password", ""))
+        s.send_message(msg)
+
+
+def dispatch(cfg: dict, level: int, msg: str, source: str) -> list[str]:
+    """Send `msg` to every configured destination. Never raises — returns a list
+    of "<dest>:ok" / "<dest>:err:<detail>" strings so callers can log results."""
+    dests = (cfg or {}).get("destinations") or {}
+    results: list[str] = []
+    subject = f"Burnmeter {LEVEL_NAMES.get(level, '')} · {source}"
+    if dests.get("webhook_url"):
+        try:
+            send_webhook(dests["webhook_url"], {
+                "source": source, "level": level,
+                "level_name": LEVEL_NAMES.get(level), "message": msg,
+            })
+            results.append("webhook:ok")
+        except Exception as e:
+            results.append(f"webhook:err:{e}")
+    if dests.get("slack_webhook_url"):
+        try:
+            send_slack(dests["slack_webhook_url"], msg)
+            results.append("slack:ok")
+        except Exception as e:
+            results.append(f"slack:err:{e}")
+    if dests.get("email"):
+        try:
+            send_email(dests["email"], subject, msg)
+            results.append("email:ok")
+        except Exception as e:
+            results.append(f"email:err:{e}")
+    return results
+
+
+def check_and_fire(reports: dict, cfg: Optional[dict] = None,
+                   state: Optional[dict] = None) -> dict:
+    """Evaluate each source's report and dispatch on an UPWARD threshold crossing.
+
+    `reports`: {source: report_dict}. `state`: {source: last_level}, mutated and
+    returned. De-dup matches dashboard.js: fire only when level >= 2 AND it is
+    higher than the previous level for that source (so a sustained warning emits
+    once, and a warn->crit escalation re-fires).
+    """
+    cfg = cfg if cfg is not None else load_config()
+    state = state if state is not None else {}
+    if not is_enabled(cfg):
+        return state
+    sources = cfg.get("sources") or list(reports.keys())
+    for source in sources:
+        rep = reports.get(source)
+        if not rep:
+            continue
+        level, msg = evaluate(rep, source)
+        prev = state.get(source, 0)
+        state[source] = level
+        if level >= 2 and level > prev:
+            dispatch(cfg, level, msg, source)
+    return state
+
+
+def send_test(cfg: Optional[dict] = None) -> list[str]:
+    """Send a test alert to every configured destination (ignores enabled/level
+    gating) so users can verify their setup."""
+    cfg = cfg if cfg is not None else load_config()
+    return dispatch(cfg, 2,
+                    "\U0001f514 Burnmeter test alert — your notification destinations work.",
+                    "test")