claude-usage-widget 0.2.0__py3-none-any.whl

claude_usage/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Usage Widget — desktop usage tracker for Claude Code."""
+
+__version__ = "0.2.0"

claude_usage/analytics.py

@@ -0,0 +1,149 @@
+"""Anomaly detection and cost-optimisation analysis over usage history.
+
+Pure module — no I/O, no GUI, no network. Given a list of sample dicts from
+history.py, produces structured reports the widget can render in the popup.
+"""
+
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass, field
+
+
+MIN_SAMPLES = 7  # Need at least a week of data before we flag anomalies
+Z_THRESHOLD = 2.0  # Standard deviations above the mean
+
+
+@dataclass
+class AnomalyReport:
+    """Summary of a single-day anomaly check."""
+
+    is_anomaly: bool = False
+    today_usage: float = 0.0
+    baseline: float = 0.0
+    std_dev: float = 0.0
+    z_score: float = 0.0
+    ratio: float = 0.0
+    reason: str = ""
+    message: str = ""
+
+
+def _daily_peaks(samples: list[dict], key: str = "session") -> list[float]:
+    """Reduce a sample stream into one max value per calendar day."""
+    by_day: dict[int, float] = {}
+    for s in samples:
+        ts = float(s.get("ts", 0))
+        if ts <= 0:
+            continue
+        day = int(ts // 86400)
+        val = float(s.get(key, 0))
+        if val > by_day.get(day, 0.0):
+            by_day[day] = val
+    return [by_day[d] for d in sorted(by_day)]
+
+
+def detect_anomaly(
+    samples: list[dict],
+    today_usage: float,
+    key: str = "session",
+) -> AnomalyReport:
+    """Return an AnomalyReport for today_usage against historical peaks."""
+    rep = AnomalyReport(today_usage=today_usage)
+
+    peaks = _daily_peaks(samples, key=key)
+    history = peaks[:-1] if peaks else []
+
+    if len(history) < MIN_SAMPLES:
+        rep.reason = f"insufficient history ({len(history)} days < {MIN_SAMPLES})"
+        return rep
+
+    rep.baseline = statistics.fmean(history)
+    rep.std_dev = statistics.pstdev(history) if len(history) > 1 else 0.0
+    if rep.baseline > 0:
+        rep.ratio = today_usage / rep.baseline
+    if rep.std_dev > 0:
+        rep.z_score = (today_usage - rep.baseline) / rep.std_dev
+
+    # Flag anomaly: either z-score exceeds threshold, OR history is flat
+    # (std_dev == 0) but today is >= 1.5x the baseline.
+    is_spike = today_usage > rep.baseline and (
+        rep.z_score >= Z_THRESHOLD
+        or (rep.std_dev == 0 and rep.ratio >= 1.5)
+    )
+    if is_spike:
+        rep.is_anomaly = True
+        rep.message = (
+            f"Today is {rep.ratio:.1f}x your {len(history)}-day average — "
+            f"{int(today_usage * 100)}% vs {int(rep.baseline * 100)}% typical."
+        )
+    return rep
+
+
+# ---------------------------------------------------------------------------
+# Cost optimisation tips
+# ---------------------------------------------------------------------------
+
+LOW_CACHE_HIT_RATE = 0.60   # below this, suggest improving caching
+OPUS_HEAVY_THRESHOLD = 0.80  # above this share of output from opus, suggest sonnet
+
+
+def _cache_hit_rate(counts: dict) -> float:
+    """Return cache_read / (cache_read + input) for one model's counts."""
+    cr = float(counts.get("cache_read", 0) or 0)
+    in_t = float(counts.get("input", 0) or 0)
+    denom = cr + in_t
+    return cr / denom if denom > 0 else 0.0
+
+
+def generate_tips(
+    by_model: dict,
+    week_cost: float,
+    cache_savings: float,
+) -> list[str]:
+    """Return 0-3 short actionable tips based on the week's usage profile."""
+    tips: list[str] = []
+    if not by_model:
+        return tips
+
+    total_output = sum(
+        float(c.get("output", 0) or 0) for c in by_model.values()
+    )
+
+    # Tip 1: cache hit rate
+    hit_rates = [
+        _cache_hit_rate(c) for c in by_model.values()
+        if float(c.get("input", 0) or 0) + float(c.get("cache_read", 0) or 0) > 10_000
+    ]
+    if hit_rates:
+        avg_hit = sum(hit_rates) / len(hit_rates)
+        if avg_hit < LOW_CACHE_HIT_RATE and week_cost > 0:
+            potential = week_cost * (0.85 - avg_hit) * 0.9
+            if potential >= 1.0:
+                tips.append(
+                    f"Cache hit rate is {int(avg_hit * 100)}%. "
+                    f"Raising to ~85% could save ~${potential:.0f}/week."
+                )
+
+    # Tip 2: model mix
+    if total_output > 100_000:
+        opus_output = sum(
+            float(c.get("output", 0) or 0)
+            for m, c in by_model.items() if "opus" in m
+        )
+        opus_share = opus_output / total_output if total_output else 0.0
+        if opus_share >= OPUS_HEAVY_THRESHOLD and week_cost > 20.0:
+            potential = week_cost * 0.70 * (opus_share - 0.5) * 0.4
+            if potential >= 1.0:
+                tips.append(
+                    f"Opus handles {int(opus_share * 100)}% of your output. "
+                    f"Shifting easy tasks to Sonnet could save ~${potential:.0f}/week."
+                )
+
+    # Tip 3: celebrate savings
+    if cache_savings > 0 and week_cost > 0 and cache_savings >= week_cost * 2:
+        tips.append(
+            f"Cache already saves ${cache_savings:.0f}/week — "
+            f"{cache_savings / max(week_cost, 1):.1f}x your bill. Keep it up."
+        )
+
+    return tips[:3]

claude_usage/api_server.py

@@ -0,0 +1,86 @@
+"""Localhost-only JSON HTTP server exposing UsageStats.
+
+Runs on a background thread so the GTK / rumps main loop is never blocked.
+Binds only to 127.0.0.1 by default; callers must explicitly opt into a
+non-loopback address via config (and then understand the auth implications).
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import asdict, is_dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Callable
+
+from claude_usage.collector import UsageStats
+
+
+class UsageAPIServer:
+    """Background HTTP server exposing /usage and /healthz."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        get_stats: Callable[[], UsageStats],
+    ) -> None:
+        self.host = host
+        self._requested_port = port
+        self._get_stats = get_stats
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    @property
+    def port(self) -> int:
+        if self._server is None:
+            return self._requested_port
+        return self._server.server_address[1]
+
+    def start(self) -> None:
+        """Bind the socket and start the background serving thread."""
+        handler_cls = self._make_handler()
+        self._server = ThreadingHTTPServer((self.host, self._requested_port), handler_cls)
+        self._thread = threading.Thread(
+            target=self._server.serve_forever, name="usage-api", daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Shut down the server and wait for its thread to exit."""
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+        if self._thread is not None:
+            self._thread.join(timeout=2)
+            self._thread = None
+
+    def _make_handler(self) -> type[BaseHTTPRequestHandler]:
+        get_stats = self._get_stats
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, fmt, *args) -> None:  # noqa: N802
+                return
+
+            def do_GET(self) -> None:  # noqa: N802
+                if self.path == "/healthz":
+                    self._send_json({"ok": True})
+                    return
+                if self.path == "/usage":
+                    stats = get_stats()
+                    data = asdict(stats) if is_dataclass(stats) else dict(stats)
+                    self._send_json(data)
+                    return
+                self.send_error(404, "Not Found")
+
+            def _send_json(self, payload: dict) -> None:
+                body = json.dumps(payload, default=str).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(body)))
+                self.send_header("Cache-Control", "no-store")
+                self.end_headers()
+                self.wfile.write(body)
+
+        return Handler

claude_usage/cli.py

@@ -0,0 +1,90 @@
+"""Command-line interface for headless / scripted access to usage stats."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict, is_dataclass
+from typing import Sequence
+
+from claude_usage import __version__
+from claude_usage.collector import UsageStats, collect_all
+from claude_usage.config import load_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argparse parser used by the CLI dispatcher."""
+    p = argparse.ArgumentParser(
+        prog="claude-usage",
+        description="Claude Code usage tracker — GUI by default, CLI on demand.",
+    )
+    p.add_argument("--version", action="store_true", help="Print version and exit.")
+    p.add_argument("--json", action="store_true", help="Emit full stats as JSON.")
+    p.add_argument("--once", action="store_true", help="Collect once and print JSON.")
+    p.add_argument("--field", metavar="NAME", default=None,
+                   help="Print a single UsageStats field by name.")
+    p.add_argument("--export", choices=("csv", "json"), default=None,
+                   help="Export history as CSV or JSON to stdout.")
+    p.add_argument("--days", type=int, default=30,
+                   help="Look-back window for --export (default: 30).")
+    return p
+
+
+def _usage_stats_to_dict(stats: UsageStats) -> dict:
+    """Convert a UsageStats dataclass to a JSON-serialisable dict."""
+    return asdict(stats) if is_dataclass(stats) else dict(stats)
+
+
+def _default_config_path() -> str:
+    base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    cfg = os.path.join(base_dir, "config.json")
+    if not os.path.isfile(cfg):
+        cfg = os.path.join(base_dir, "config.json.example")
+    return cfg
+
+
+def run_cli(argv: Sequence[str]) -> int:
+    """Dispatch a single CLI invocation. Returns a process exit code."""
+    args = build_parser().parse_args(list(argv))
+
+    if args.version:
+        print(__version__)
+        return 0
+
+    if args.export:
+        from claude_usage.exporter import export_history
+        config = load_config(_default_config_path())
+        history_path = os.path.join(config["claude_dir"], "usage-history.jsonl")
+        count = export_history(history_path, fmt=args.export, days=args.days, out=sys.stdout)
+        print(f"# exported {count} samples", file=sys.stderr)
+        return 0
+
+    if args.json or args.once or args.field:
+        config = load_config(_default_config_path())
+        stats = collect_all(config)
+        data = _usage_stats_to_dict(stats)
+
+        if args.field is not None:
+            if args.field not in data:
+                print(f"error: unknown field {args.field!r}", file=sys.stderr)
+                return 2
+            print(data[args.field])
+            return 0
+
+        json.dump(data, sys.stdout, default=str, indent=2, sort_keys=True)
+        print()
+        return 0
+
+    # No CLI flag — caller should fall through to GUI.
+    return -1
+
+
+def main() -> int:
+    """Entry point for the ``claude-usage`` console script."""
+    return run_cli(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())