cctrack 0.6.0__tar.gz → 0.7.0__tar.gz

{cctrack-0.6.0 → cctrack-0.7.0}/CLAUDE.md

@@ -35,10 +35,11 @@ This is a single-module CLI tool. All logic lives in `src/cctrack/__init__.py`:
 1a. **Energy model** (`ENERGY_WH_PER_MTOK`, `estimate_energy_wh`) - Opt-in (`--energy`) order-of-magnitude estimate keyed off each rate entry's `tier`. Deliberately NOT a function of price: both cache-write TTLs use one figure because a 1h write costs more money but the same compute.
 2. **File discovery** (`default_dirs`, `discover_files`) - Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for `.jsonl` files.
 3. **Remote aggregation** (`fetch_remote_jsonl`, `parse_remote_events`, `fetch_remote_hook_data`, `parse_remote_hook_data`) - SSHs to hosts, cats all JSONL logs plus statusline hook data (statusline files, monthly summaries, session baselines) with file separators, parses locally.
-3a. **Hook parsing** (`parse_hook_rows`, `compute_hook_deltas`, `_cost_increment`) - The hook is authoritative for **cost only**. Its `input_tokens`/`output_tokens`/`cache_*` fields are context-window SNAPSHOTS (`input_tokens` ≈ `cache_read + cache_write`; `output_tokens` is just the last message's), not cumulative — never use them for token counts. `cost_usd` is a per-session running total, but it RESTARTS on resume/compaction and a render can report 0, so deltas walk every row chronologically and treat a meaningful drop as a restart.
+3a. **Hook parsing** (`parse_hook_rows`, `compute_hook_deltas`) - The hook gives **cost only**. Its `input_tokens`/`output_tokens`/`cache_*` fields are context-window SNAPSHOTS (`input_tokens` ≈ `cache_read + cache_write`; `output_tokens` is just the last message's), not cumulative — never use them for token counts. `cost_usd` is a session-lifetime cumulative that is unreliable in two ways handled by `compute_hook_deltas`: (1) it can already be large the first time a session is observed (a long-running/unattended session that only rendered its statusline partway through), so the **first observation is a baseline that is NOT counted** — booking a session's pre-existing cumulative onto its first-seen day is what produced a bogus $3,370 day; (2) it **drops** on resume/compaction (or when parallel processes share one session id), so a drop **rebaselines without counting the new level** — otherwise a day's booked spend can exceed the counter's own peak, which is impossible for real money. Net rule: **book only observed upward increments**; a rolled-up baseline seeds `prev` so already-counted days aren't recounted.
 4. **JSONL parsing** (`parse_lines`, `parse_events`, `dedup_events`) - Extracts `assistant` events with token usage. Deduplicates by `requestId` across all of a host's files (last event wins) — resumed sessions (`--resume`/`--continue`) repeat events with the same `requestId` in new files. Events without `requestId` are never deduped.
 5. **Aggregation** (`aggregate`) - Buckets events into daily and monthly summaries with token counts and costs.
 6. **Output** (`print_report`) - Prints current month-to-date summary with projections, daily breakdown, and previous month summaries. Cost is composed **per source** (one source per machine): hook cost where a source has statusline coverage, accuracy-factor-adjusted JSONL cost otherwise, summed per date. The accuracy factor is measured per source over dates strictly after that source's hook install day.
+6a. **Explore** (`print_explore`, `--explore DATE`) - Drills into one day: dollar decomposition by token class, then by model / project / session / machine. Each JSONL event carries its `project` (from `cwd`), `session_id`, `source` (host) and `git_branch` for attribution. Per-session JSONL estimate is shown against the hook's authoritative per-session cost; a >15% day-total divergence is flagged so an inflated estimate (incomplete logs, unknown model) is distinguishable from real spend.
 
 Entry point: `cctrack:main` (registered in `pyproject.toml` as a console script).
 
@@ -48,7 +49,7 @@ Entry point: `cctrack:main` (registered in `pyproject.toml` as a console script)
 - Deduplication is global per host by `requestId` (last wins) - resumed sessions replay history into new files and must not double count. Cross-host `requestId` collisions can't occur (distinct API calls).
 - Hook data is authoritative for **cost only**; every token count comes from the JSONL logs. Never mix the two in one figure - the hook's token fields are snapshots and would double count against JSONL cache columns.
 - Never let one machine's hook coverage suppress another machine's JSONL cost - compose per source.
-- Cumulative counters from the hook are not monotonic. Any code differencing `cost_usd` must handle restarts (resume/compaction) and zero-valued renders, or whole days silently vanish.
+- Cumulative counters from the hook are not monotonic and don't start at zero when first observed. `compute_hook_deltas` books only observed upward increments (first observation and post-drop levels are baselines, never counted), so a day's hook cost can never exceed the counter's peak and a session's pre-observation history is never mis-dated onto its first-seen day. Test fixtures must start sessions at ~$0 to mirror real statusline behavior.
 - `session-baselines.json` carries each session's rolled-up cumulative across the 90-day retention boundary so straddling sessions aren't re-counted from zero.
 - Build system is Hatch (`hatchling`)
 - Requires Python 3.10+

{cctrack-0.6.0 → cctrack-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctrack
-Version: 0.6.0
+Version: 0.7.0
 Summary: Claude Code cost tracker — scans JSONL logs and reports token usage + estimated cost
 Project-URL: Homepage, https://github.com/rappdw/cctrack
 Project-URL: Repository, https://github.com/rappdw/cctrack
@@ -84,6 +84,32 @@ Daily breakdown:
 4. Calculates cost using Anthropic's published rates per model
 5. Prints daily breakdown with input/output/cache token splits and monthly summaries
 
+## Explore a day
+
+When a day's cost looks wrong or surprisingly high, `--explore` breaks it down:
+
+```bash
+cctrack --explore 2026-08-03          # a specific day
+cctrack --explore yesterday           # or 'today'
+cctrack --explore yesterday --remote air dgx   # across machines
+```
+
+It reports, for that day:
+
+- **Where it went** — the day's cost decomposed by token class (output, 1h/5m cache writes, input, cache reads), so a cache-write blowup or a runaway output loop is obvious at a glance.
+- **By model / by project / by machine** — cost and share for each, so you can see which model, which repo, and which host drove it.
+- **Top sessions** — ranked by cost, each with its project and model, and — where the statusline hook covered that session — its **authoritative** cost next to the JSONL estimate.
+
+The day's JSONL-estimated total is shown next to the hook-authoritative total. If they diverge by more than ~15% the report says so: a big gap means the estimate is off (incomplete logs, or a model the rate card doesn't know), not that you actually spent that much. This is the fastest way to tell a real expensive day from an accounting artifact.
+
+The project label is the basename of each session's working directory (`cwd`). When that's an unfamiliar name — a container path like `/workspace/team-inbox`, or a directory you don't recognize — trace it to its real location:
+
+```bash
+cctrack --explore 2026-08-03 --project team-inbox
+```
+
+This restricts the view to that project and prints each session's full `cwd`, git branch, and the log file on disk (which reveals the host directory or the specific Sandy sandbox it came from). The unfiltered view flags this automatically when a `cwd` looks like a container path. `scripts/trace_project.py` and `scripts/diagnose_session_cost.py` are standalone versions of the trace and per-session cost diagnostics.
+
 ## Remote aggregation
 
 With `--remote`, cctrack SSHs to each host and streams back both the JSONL logs and the host's statusline hook data (`~/.claude/cctrack/`) for local parsing, so authoritative hook costs from every machine are summed per day. Requires SSH key auth.

{cctrack-0.6.0 → cctrack-0.7.0}/README.md

@@ -59,6 +59,32 @@ Daily breakdown:
 4. Calculates cost using Anthropic's published rates per model
 5. Prints daily breakdown with input/output/cache token splits and monthly summaries
 
+## Explore a day
+
+When a day's cost looks wrong or surprisingly high, `--explore` breaks it down:
+
+```bash
+cctrack --explore 2026-08-03          # a specific day
+cctrack --explore yesterday           # or 'today'
+cctrack --explore yesterday --remote air dgx   # across machines
+```
+
+It reports, for that day:
+
+- **Where it went** — the day's cost decomposed by token class (output, 1h/5m cache writes, input, cache reads), so a cache-write blowup or a runaway output loop is obvious at a glance.
+- **By model / by project / by machine** — cost and share for each, so you can see which model, which repo, and which host drove it.
+- **Top sessions** — ranked by cost, each with its project and model, and — where the statusline hook covered that session — its **authoritative** cost next to the JSONL estimate.
+
+The day's JSONL-estimated total is shown next to the hook-authoritative total. If they diverge by more than ~15% the report says so: a big gap means the estimate is off (incomplete logs, or a model the rate card doesn't know), not that you actually spent that much. This is the fastest way to tell a real expensive day from an accounting artifact.
+
+The project label is the basename of each session's working directory (`cwd`). When that's an unfamiliar name — a container path like `/workspace/team-inbox`, or a directory you don't recognize — trace it to its real location:
+
+```bash
+cctrack --explore 2026-08-03 --project team-inbox
+```
+
+This restricts the view to that project and prints each session's full `cwd`, git branch, and the log file on disk (which reveals the host directory or the specific Sandy sandbox it came from). The unfiltered view flags this automatically when a `cwd` looks like a container path. `scripts/trace_project.py` and `scripts/diagnose_session_cost.py` are standalone versions of the trace and per-session cost diagnostics.
+
 ## Remote aggregation
 
 With `--remote`, cctrack SSHs to each host and streams back both the JSONL logs and the host's statusline hook data (`~/.claude/cctrack/`) for local parsing, so authoritative hook costs from every machine are summed per day. Requires SSH key auth.

{cctrack-0.6.0 → cctrack-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctrack"
-version = "0.6.0"
+version = "0.7.0"
 description = "Claude Code cost tracker — scans JSONL logs and reports token usage + estimated cost"
 readme = "README.md"
 license = "MIT"

cctrack-0.7.0/scripts/diagnose_session_cost.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Diagnose a cctrack --explore day and show what each session really spent.
+
+The hook's `total_cost_usd` is a session-lifetime cumulative that (a) can be
+large the moment cctrack first sees a long-running session, and (b) drops on
+resume/compaction. cctrack 0.6.0 mis-attributed both: it booked a session's
+whole pre-existing cumulative onto the first day it saw the session, and it
+re-added post-drop levels as fresh spend — so a session whose counter never
+passed $1,086 could be reported at $2,083, and a day's total could balloon far
+above real spend.
+
+This script reads the raw statusline data for a date and, per session, prints:
+
+  * the cost_usd trajectory,
+  * BUGGY: what cctrack ≤0.6.0 booked (first level + every post-drop level),
+  * FIXED: what cctrack now books — only observed increments, never the
+    standing level (== the honest spend cctrack can see on that day).
+
+If FIXED is far below BUGGY, the old report was inflated. FIXED is what the
+corrected cctrack reports; any spend from earlier days the hook didn't capture
+is genuinely unattributable and isn't booked on this day.
+
+Usage:
+    python3 scripts/diagnose_session_cost.py <YYYY-MM-DD> [session_prefix ...]
+
+    # every session that has data that day:
+    python3 scripts/diagnose_session_cost.py 2026-08-03
+
+    # just specific ones (any unique prefix of the session id works):
+    python3 scripts/diagnose_session_cost.py 2026-08-03 34dfdf14 63fd9dae 7c112e0a
+
+Reads ~/.claude/cctrack and any ~/.sandy/sandboxes/*/claude/cctrack. Stdlib only.
+"""
+import glob
+import json
+import sys
+from pathlib import Path
+
+
+def buggy_increment(cur: float, prev: float) -> float:
+    """What cctrack <= 0.6.0 did: a meaningful drop counted the new value in
+    full (and prev started at 0, so the first reading counted in full too)."""
+    if cur < prev - max(1e-6, abs(prev) * 0.001):
+        return max(0.0, cur)
+    return max(0.0, cur - prev)
+
+
+def hook_dirs() -> list[Path]:
+    dirs = [Path.home() / ".claude" / "cctrack"]
+    dirs += [Path(p) for p in glob.glob(
+        str(Path.home() / ".sandy" / "sandboxes" / "*" / "claude" / "cctrack"))]
+    return [d for d in dirs if d.exists()]
+
+
+def load_rows(date_str: str) -> dict[str, list[tuple[str, float]]]:
+    """Return {session_id: [(ts, cost_usd), ...]} for the given date."""
+    rows: dict[str, list[tuple[str, float]]] = {}
+    for d in hook_dirs():
+        for f in glob.glob(str(d / f"statusline-{date_str}.jsonl")):
+            try:
+                lines = Path(f).read_text(errors="replace").splitlines()
+            except OSError:
+                continue
+            for line in lines:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    e = json.loads(line)
+                except (json.JSONDecodeError, ValueError):
+                    continue
+                sid = e.get("session_id", "")
+                ts = e.get("_ts", "")
+                if not sid or not ts:
+                    continue
+                rows.setdefault(sid, []).append((ts, float(e.get("cost_usd", 0) or 0)))
+    return rows
+
+
+def analyze(sid: str, seq: list[tuple[str, float]]) -> dict:
+    seq.sort()
+    costs = [c for _, c in seq]
+
+    # BUGGY (<= 0.6.0): prev starts at 0; drops re-add the full new level.
+    buggy = prev = 0.0
+    drops = 0
+    for c in costs:
+        if c < prev - max(1e-6, abs(prev) * 0.001):
+            drops += 1
+        buggy += buggy_increment(c, prev)
+        prev = c
+
+    # FIXED: first reading is a baseline (not counted); a drop rebaselines
+    # (not counted); only genuine upward increments are booked.
+    fixed = 0.0
+    prev = None
+    for c in costs:
+        if prev is None:
+            prev = c
+        elif c < prev - max(1e-6, abs(prev) * 0.001):
+            prev = c
+        else:
+            fixed += c - prev
+            prev = c
+
+    return {
+        "sid": sid,
+        "renders": len(costs),
+        "min": min(costs),
+        "max": max(costs),
+        "first": costs[0],
+        "last": costs[-1],
+        "drops": drops,
+        "buggy": buggy,
+        "fixed": fixed,
+        "costs": costs,
+    }
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return 2
+
+    date_str = sys.argv[1]
+    prefixes = sys.argv[2:]
+
+    rows = load_rows(date_str)
+    if not rows:
+        print(f"No statusline data found for {date_str} in:")
+        for d in hook_dirs() or ["(no hook directories exist)"]:
+            print(f"  {d}")
+        return 1
+
+    selected = {sid: seq for sid, seq in rows.items()
+                if not prefixes or any(sid.startswith(p) for p in prefixes)}
+    if not selected:
+        print(f"No sessions matching {prefixes} on {date_str}. "
+              f"Sessions present: {', '.join(s[:12] for s in rows)}")
+        return 1
+
+    results = [analyze(sid, seq) for sid, seq in selected.items()]
+    results.sort(key=lambda r: -r["buggy"])
+
+    grand_buggy = grand_fixed = 0.0
+    for r in results:
+        grand_buggy += r["buggy"]
+        grand_fixed += r["fixed"]
+        inflation = (r["buggy"] / r["fixed"]) if r["fixed"] > 0.005 else float("inf")
+        tag = "" if inflation < 1.15 else f"  ← inflated {inflation:.0f}×" if inflation != float("inf") else "  ← booked from nothing"
+        print(f"\n=== {r['sid'][:12]}  ({r['renders']} renders) ===")
+        print(f"  cost_usd   first={r['first']:.2f}  min={r['min']:.2f}  "
+              f"max={r['max']:.2f}  last={r['last']:.2f}  drops={r['drops']}")
+        print(f"  BUGGY (cctrack ≤0.6.0 booked on this day): ${r['buggy']:.2f}{tag}")
+        print(f"  FIXED (real observed spend this day):      ${r['fixed']:.2f}")
+        shown = " ".join(f"{c:.1f}" for c in r["costs"][:40])
+        print(f"  trajectory: {shown}" + (" …" if len(r["costs"]) > 40 else ""))
+
+    print(f"\n{'─' * 60}")
+    print(f"selected sessions — buggy total: ${grand_buggy:.2f}   fixed total: ${grand_fixed:.2f}")
+    if grand_fixed > 0.005 and grand_buggy / grand_fixed > 1.15:
+        print(f"The old report over-stated these sessions by "
+              f"{grand_buggy / grand_fixed:.1f}×. The FIXED column is the honest")
+        print("spend cctrack can see for this day. Any earlier-day spend the hook")
+        print("never captured is unattributable and is not booked here.")
+    else:
+        print("Buggy and fixed agree — these sessions were attributed correctly.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cctrack-0.7.0/scripts/trace_project.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Trace where a cctrack --explore project label actually comes from.
+
+`--explore` labels each session by the basename of the `cwd` recorded on its
+JSONL events (e.g. a cwd of /workspace/team-inbox shows as "team-inbox"). That
+basename can be a container/automation path that doesn't match any sandbox or
+directory you recognize. This script shows the FULL cwd, the git branch, the
+session id, and the exact log file on disk for a project or session, so you can
+see where the events physically are.
+
+Usage:
+    python3 scripts/trace_project.py [YYYY-MM-DD] [name_or_prefix ...]
+
+    # everything logged yesterday, grouped by project:
+    python3 scripts/trace_project.py 2026-08-03
+
+    # just the mystery project (matches project basename OR session-id prefix):
+    python3 scripts/trace_project.py 2026-08-03 team-inbox
+
+    # a whole date range is not supported; omit the date to scan all logs:
+    python3 scripts/trace_project.py team-inbox
+
+Scans ~/.claude/projects and ~/.sandy/sandboxes/*/... for *.jsonl. Stdlib only.
+"""
+import glob
+import json
+import sys
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+
+
+def is_date(tok: str) -> bool:
+    try:
+        datetime.strptime(tok, "%Y-%m-%d")
+        return True
+    except ValueError:
+        return False
+
+
+def scan_dirs() -> list[Path]:
+    home = Path.home()
+    roots = [home / ".claude" / "projects"]
+    sandy = home / ".sandy" / "sandboxes"
+    if sandy.exists():
+        roots.append(sandy)
+    files: list[Path] = []
+    for root in roots:
+        if root.exists():
+            files += [Path(p) for p in glob.glob(str(root / "**" / "*.jsonl"), recursive=True)]
+    return files
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    date_str = None
+    if args and is_date(args[0]):
+        date_str = args[0]
+        args = args[1:]
+    filters = args  # project basenames or session-id prefixes
+
+    def matches(project: str, sid: str) -> bool:
+        if not filters:
+            return True
+        return any(project == f or project.endswith(f) or sid.startswith(f) for f in filters)
+
+    # key: (cwd, sessionId, file) -> {count, models, branches, first, last}
+    groups: dict[tuple, dict] = defaultdict(
+        lambda: {"count": 0, "models": set(), "branches": set(), "first": "", "last": ""})
+
+    files = scan_dirs()
+    for f in files:
+        try:
+            lines = f.read_text(errors="replace").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                e = json.loads(line)
+            except (json.JSONDecodeError, ValueError):
+                continue
+            if e.get("type") != "assistant":
+                continue
+            ts = e.get("timestamp", "")
+            if date_str and not ts.startswith(date_str):
+                continue
+            cwd = e.get("cwd", "")
+            project = Path(cwd).name if cwd else "(unknown)"
+            sid = e.get("sessionId", "")
+            if not matches(project, sid):
+                continue
+            g = groups[(cwd, sid, str(f))]
+            g["count"] += 1
+            model = e.get("message", {}).get("model", "")
+            if model:
+                g["models"].add(model)
+            if e.get("gitBranch"):
+                g["branches"].add(e["gitBranch"])
+            if ts:
+                g["first"] = ts if not g["first"] else min(g["first"], ts)
+                g["last"] = max(g["last"], ts)
+
+    if not groups:
+        where = f" on {date_str}" if date_str else ""
+        filt = f" matching {filters}" if filters else ""
+        print(f"No assistant events{filt}{where} found in ~/.claude/projects or ~/.sandy/sandboxes.")
+        return 1
+
+    # Group the display by project basename.
+    by_project: dict[str, list[tuple]] = defaultdict(list)
+    for (cwd, sid, f), g in groups.items():
+        by_project[Path(cwd).name if cwd else "(unknown)"].append((cwd, sid, f, g))
+
+    for project in sorted(by_project):
+        rows = by_project[project]
+        total = sum(g["count"] for *_ , g in rows)
+        print(f"\n=== project '{project}'  ({total} assistant events, "
+              f"{len(set(s for _, s, _, _ in rows))} sessions) ===")
+        # distinct cwds under this basename (reveals collisions / container paths)
+        for cwd in sorted(set(c for c, _, _, _ in rows)):
+            print(f"  cwd: {cwd or '(empty)'}")
+        for cwd, sid, f, g in sorted(rows, key=lambda r: -r[3]["count"]):
+            branch = ",".join(sorted(g["branches"])) or "-"
+            models = ",".join(sorted(m.replace("claude-", "") for m in g["models"])) or "-"
+            print(f"    session {sid[:12]}  {g['count']:>4} ev  branch={branch}  model={models}")
+            print(f"      {g['first'][:19]} … {g['last'][:19]}")
+            print(f"      file: {f}")
+    print()
+    print("The `cwd` line is the working directory Claude Code recorded — that is")
+    print("the real source of the project label. If it's a container/automation")
+    print("path (e.g. /workspace/...), the run happened inside that environment,")
+    print("not a host directory or sandbox of that name.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())