cctrack 0.6.0__tar.gz → 0.8.0__tar.gz

cctrack-0.8.0/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+cctrack-py is a zero-dependency Python CLI that scans Claude Code and Codex CLI log files and reports token usage and estimated cost. It's a Python port of the Go-based [cctrack dashboard](https://github.com/ksred/cctrack), stripped down to a single command that parses logs and prints a cost report.
+
+## Commands
+
+```bash
+# Install in development mode
+uv pip install -e .
+
+# Run the tool
+python -m cctrack
+# or after install:
+cctrack
+
+# Run all tests
+python -m pytest tests/
+
+# Run a single test
+python -m pytest tests/test_cctrack.py::test_name
+
+# Build distribution
+uv build
+```
+
+## Architecture
+
+This is a single-module CLI tool. All logic lives in `src/cctrack/__init__.py`:
+
+1. **Rate card** (`RATES`, `_an`/`_oa` row builders, `_family_matches`, `get_rates`, `calculate_cost`, `is_known_model`) - Anthropic and OpenAI prices. **Every model version needs its own row**: `_family_matches` lets a row absorb only the exact id, dated snapshots (`-20250514`, `-2025-08-07`) and non-version suffixes (`-codex`) — never a short-number minor version (`claude-opus-5` does NOT match `claude-opus-5-5`) or a size-tier word (`mini`, `nano`, `pro`, `max`, `luna`, `terra`, `sol`, `astra`). This is deliberate: prefix inheritance silently mispriced opus-4-8 (3×) and opus-5-5 (84%) before. Unknown models are flagged `?` and fall back to Sonnet (Claude) or GPT-5 (OpenAI) rates. `get_rates` takes the usage date (time-limited `intro` pricing) and the request's prompt size (`long_context` tiers: Haiku 5.5 >100K, several OpenAI models >272K). Re-verify against the official pricing pages when adding rows; don't infer a price from a neighbouring model.
+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.
+2a. **Codex** (`discover_codex_files`, `parse_codex_lines`, `parse_codex_events`, `fetch_remote_codex`) - Reads `$CODEX_HOME` (default `~/.codex`) `sessions/` + `archived_sessions/` rollouts, incl. `.jsonl.zst` (stdlib `compression.zstd` on 3.14+, else the `zstd` CLI, else skipped and counted). Lines are `{timestamp, type, payload}`. Prefer `token_usage_record` items (per-response, dedup by `response_id` — forks replay parent history); fall back to legacy `event_msg`/`token_count` only before a file's first record, counting `last_token_usage` only when `total_token_usage.total_tokens` moved (it's re-emitted unchanged). **`input_tokens` includes `cached_input_tokens` and `cache_write_input_tokens`; `output_tokens` includes reasoning** — uncached input = input − cached − cache_write. Model/cwd from the latest `turn_context`; thread id + git branch from `session_meta`. Codex events carry `agent="codex"`.
+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`) - 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).
+
+## Key Design Decisions
+
+- Zero external dependencies - stdlib only (json, argparse, subprocess, etc.)
+- 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.
+- Each coding agent is its own source. Codex sources are `exact`: priced straight from their logs, never replaced by the Claude hook and never scaled by the (Claude-derived) accuracy factor. In `--explore`, hook comparisons use only the Claude slice of the JSONL total.
+- Costs are API list prices. For subscription users (ChatGPT plans, Claude subscriptions) they're API-equivalent values, not invoices.
+- 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.8.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.5
+Name: cctrack
+Version: 0.8.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
+Project-URL: Issues, https://github.com/rappdw/cctrack/issues
+Author: Dan Rapp
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,cost,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cctrack
+
+A lightweight CLI tool that scans [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex CLI](https://github.com/openai/codex) logs and reports token usage and estimated cost. Zero dependencies, runs anywhere Python 3.10+ is available.
+
+## Install
+
+```bash
+# Run directly (no install needed)
+uvx cctrack
+
+# Or install globally
+uv tool install cctrack
+```
+
+## Usage
+
+```bash
+# Scan local logs and print report
+cctrack
+
+# Last 7 days only
+cctrack --days 7
+
+# Aggregate with remote machines via SSH
+cctrack --remote dgx macbook-air
+
+# Custom log directories
+cctrack --dirs ~/.claude/projects ~/.sandy/sandboxes
+
+# Only one coding agent (default: all found)
+cctrack --agent claude
+cctrack --agent codex
+```
+
+## Example output
+
+```
+cctrack — Claude Code Cost Report
+══════════════════════════════════
+
+April 2026 — month to date (day 1, 1 active)
+───────────────────────────────────────
+  Input tokens:            23,381
+  Output tokens:          199,069
+  Cache read:          30,862,977
+  Cache write:          1,051,023
+  Total tokens:        32,136,450
+  Total cost:     $25.85
+  Avg/day:        $25.85
+  Projected/mo:   $775.50 (based on 1-day avg)
+
+Daily breakdown:
+  Date                Input       Output      Cache R      Cache W       Cost
+  ──────────── ──────────── ──────────── ──────────── ──────────── ──────────
+  2026-04-01         23,381      199,069   30,862,977    1,051,023 $   25.85
+```
+
+## What it does
+
+1. Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for JSONL log files
+2. Parses `assistant` events with token usage
+3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
+4. Calculates cost using Anthropic's published rates per model
+5. Prints daily breakdown with input/output/cache token splits and monthly summaries
+
+## Codex CLI
+
+cctrack also reads [Codex CLI](https://github.com/openai/codex) usage from `$CODEX_HOME` (default `~/.codex`) — `sessions/` and `archived_sessions/` — and with `--remote`, from each host. When both agents have spend, the month-to-date block and `--explore` show a per-agent split.
+
+How it's counted (verified against the Codex source, not inferred):
+
+- **Per-response usage.** Newer Codex versions log a `token_usage_record` for every API response with a unique `response_id`; those are counted and deduplicated across files, so forked and resumed threads (which replay their parent's history) aren't double counted. Older versions only log `token_count` events, which are re-emitted with unchanged totals — only events whose running total moved are counted.
+- **Cached tokens are inside `input_tokens`.** Codex reports cached reads and cache writes as parts of `input_tokens`, and reasoning tokens as part of `output_tokens`. Billable uncached input is `input − cached − cache_write`; reasoning is never added on top.
+- **Its own cost source.** Codex spend is priced directly from its logs and is never replaced by, or scaled with, Claude Code's statusline-hook figures.
+- **Compressed rollouts.** Codex compresses older rollouts to `.jsonl.zst`. Python's standard library only reads zstd from 3.14, so on older Pythons cctrack uses the `zstd` command if it's installed, and otherwise skips those files and says how many it skipped.
+
+Costs are at OpenAI's **API list prices**. If you use Codex through a ChatGPT plan, that's an API-equivalent value, not what you're billed — the same is true of Claude Code on a Claude subscription.
+
+## 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.
+
+```bash
+# Aggregate this machine + DGX server + laptop
+cctrack --remote dgx macbook-air
+
+# For accurate aggregate costs, install the hook on each host too
+cctrack --install-hook --remote dgx macbook-air
+```
+
+## Rate card
+
+Prices per million tokens. Claude prices are from [Anthropic's pricing page](https://platform.claude.com/docs/en/about-claude/pricing); cache writes are priced per TTL (5-minute and 1-hour).
+
+| Claude model | Input | Output | Cache Read | Cache Write 5m | Cache Write 1h |
+|---|---|---|---|---|---|
+| Fable 5.1 / Mythos 5.1 | $10.00 | $50.00 | $0.25 | $12.50 | $20.00 |
+| Fable 5 / Mythos 5 | $10.00 | $50.00 | $1.00 | $12.50 | $20.00 |
+| Opus 5.5 | $4.00 | $20.00 | $0.20 | $5.00 | $8.00 |
+| Opus 5 / 4.8 / 4.7 / 4.6 / 4.5 | $5.00 | $25.00 | $0.50 | $6.25 | $10.00 |
+| Opus 4.1 / 4 | $15.00 | $75.00 | $1.50 | $18.75 | $30.00 |
+| Sonnet 5.5 | $2.00 | $10.00 | $0.10 | $2.50 | $4.00 |
+| Sonnet 5 | $2.00 | $10.00 | $0.20 | $2.50 | $4.00 |
+| Sonnet 4.6 / 4.5 / 4 / 3.7 | $3.00 | $15.00 | $0.30 | $3.75 | $6.00 |
+| Haiku 5.5 (prompt ≤ 100K) | $0.10 | $0.50 | $0.01 | $0.125 | $0.20 |
+| Haiku 5.5 (prompt > 100K) | $0.50 | $2.50 | $0.05 | $0.625 | $1.00 |
+| Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 | $2.00 |
+| Haiku 3.5 | $0.80 | $4.00 | $0.08 | $1.00 | $1.60 |
+| Haiku 3 | $0.25 | $1.25 | $0.03 | $0.30 | $0.50 |
+
+OpenAI prices (for Codex) are from [OpenAI's pricing page](https://developers.openai.com/api/docs/pricing), Standard tier. OpenAI has a single cache-write price, listed only for some models; elsewhere cache writes bill as ordinary input.
+
+| OpenAI model | Input | Cached input | Output | Cache write | Over 272K input |
+|---|---|---|---|---|---|
+| gpt-6-astra | $10.00 | $1.00 | $50.00 | $12.50 | $20 / $2 / $75 / $25 |
+| gpt-6.1-sol | $2.00 | $0.10 | $10.00 | $2.50 | $4 / $0.20 / $15 / $5 |
+| gpt-6-sol | $2.00 | $0.20 | $10.00 | $2.50 | $4 / $0.40 / $15 / $5 |
+| gpt-6-luna | $0.10 | $0.01 | $0.50 | $0.125 | $0.20 / $0.02 / $0.75 / $0.25 |
+| gpt-5.6-sol | $4.00 | $0.40 | $20.00 | $5.00 | $8 / $0.80 / $30 / $10 |
+| gpt-5.6-terra | $2.00 | $0.20 | $12.00 | $2.50 | $4 / $0.40 / $18 / $5 |
+| gpt-5.6-luna | $0.20 | $0.02 | $1.20 | $0.25 | $0.40 / $0.04 / $1.80 / $0.50 |
+| gpt-5.5 | $5.00 | $0.50 | $30.00 | — | $10 / $1 / $45 |
+| gpt-5.5-pro / gpt-5.4-pro | $30.00 | — | $180.00 | — | $60 / — / $270 |
+| gpt-5.4 | $2.50 | $0.25 | $15.00 | — | $5 / $0.50 / $22.50 |
+| gpt-5.4-mini | $0.75 | $0.075 | $4.50 | — | |
+| gpt-5.4-nano | $0.20 | $0.02 | $1.25 | — | |
+| gpt-5.3-codex / gpt-5.2 | $1.75 | $0.175 | $14.00 | — | |
+| gpt-5.2-pro | $21.00 | — | $168.00 | — | |
+| gpt-5.1 / gpt-5 | $1.25 | $0.125 | $10.00 | — | |
+| gpt-5-pro | $15.00 | — | $120.00 | — | |
+| gpt-5-mini | $0.25 | $0.025 | $2.00 | — | |
+| gpt-5-nano | $0.05 | $0.005 | $0.40 | — | |
+
+Codex variants without their own price (e.g. `gpt-5.1-codex`) are priced as their base model, consistent with the one variant OpenAI does list (`gpt-5.3-codex` = `gpt-5.2`). Long-context and Haiku 5.5 prompt-length tiers are applied per request.
+
+**Every model version has its own row.** A model only matches a row if it is that version or a dated snapshot of it — never a newer minor version. So a newly released model (say `claude-opus-5-7`, or `gpt-5.1-codex-mini`) shows as unknown and is flagged with `?` in the Model column, rather than silently inheriting its predecessor's price. Unknown Claude models are estimated at Sonnet rates, unknown OpenAI models at GPT-5 rates. Pricing is date-aware, so any time-limited introductory price applies only to usage on the days it was in effect.
+
+## Energy estimate
+
+`cctrack --energy` adds an estimated inference energy column (Wh/kWh):
+
+```bash
+cctrack --energy
+```
+
+This is a **rough estimate, not a measurement** — Anthropic does not publish per-token energy figures or model sizes. It is modelled from logged tokens using the published full-stack per-prompt figures the major labs have disclosed (Google: 0.24 Wh median Gemini text prompt; OpenAI: ~0.34 Wh average ChatGPT query — both include accelerator, host, cooling and idle capacity), apportioned across token classes by relative compute cost and scaled by model tier:
+
+- **output tokens dominate** — decode is sequential and memory-bandwidth bound
+- **input and cache writes** are prefill: parallel, far cheaper per token
+- **cache reads** skip prefill entirely (~0.1× input)
+- both cache-write TTLs use the same figure — a 1-hour write costs more money but the same compute
+
+Treat results as ±1 order of magnitude. It covers datacenter inference only: not model training, and not your own machine. Scale the whole model with `CCTRACK_ENERGY_SCALE=1.5` if you have better numbers for your workload.
+
+## Origins
+
+This is a Python rewrite of the Go-based [cctrack dashboard](https://github.com/ksred/cctrack). The Go version provides a full web dashboard with real-time updates, session explorer, and project breakdown. This Python version strips it down to the essentials: a single command that parses logs and prints a cost report. The JSONL parsing logic, deduplication strategy, and rate card are ported directly from the Go implementation.
+
+## License
+
+[MIT](LICENSE)

cctrack-0.8.0/README.md

@@ -0,0 +1,187 @@
+# cctrack
+
+A lightweight CLI tool that scans [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex CLI](https://github.com/openai/codex) logs and reports token usage and estimated cost. Zero dependencies, runs anywhere Python 3.10+ is available.
+
+## Install
+
+```bash
+# Run directly (no install needed)
+uvx cctrack
+
+# Or install globally
+uv tool install cctrack
+```
+
+## Usage
+
+```bash
+# Scan local logs and print report
+cctrack
+
+# Last 7 days only
+cctrack --days 7
+
+# Aggregate with remote machines via SSH
+cctrack --remote dgx macbook-air
+
+# Custom log directories
+cctrack --dirs ~/.claude/projects ~/.sandy/sandboxes
+
+# Only one coding agent (default: all found)
+cctrack --agent claude
+cctrack --agent codex
+```
+
+## Example output
+
+```
+cctrack — Claude Code Cost Report
+══════════════════════════════════
+
+April 2026 — month to date (day 1, 1 active)
+───────────────────────────────────────
+  Input tokens:            23,381
+  Output tokens:          199,069
+  Cache read:          30,862,977
+  Cache write:          1,051,023
+  Total tokens:        32,136,450
+  Total cost:     $25.85
+  Avg/day:        $25.85
+  Projected/mo:   $775.50 (based on 1-day avg)
+
+Daily breakdown:
+  Date                Input       Output      Cache R      Cache W       Cost
+  ──────────── ──────────── ──────────── ──────────── ──────────── ──────────
+  2026-04-01         23,381      199,069   30,862,977    1,051,023 $   25.85
+```
+
+## What it does
+
+1. Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for JSONL log files
+2. Parses `assistant` events with token usage
+3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
+4. Calculates cost using Anthropic's published rates per model
+5. Prints daily breakdown with input/output/cache token splits and monthly summaries
+
+## Codex CLI
+
+cctrack also reads [Codex CLI](https://github.com/openai/codex) usage from `$CODEX_HOME` (default `~/.codex`) — `sessions/` and `archived_sessions/` — and with `--remote`, from each host. When both agents have spend, the month-to-date block and `--explore` show a per-agent split.
+
+How it's counted (verified against the Codex source, not inferred):
+
+- **Per-response usage.** Newer Codex versions log a `token_usage_record` for every API response with a unique `response_id`; those are counted and deduplicated across files, so forked and resumed threads (which replay their parent's history) aren't double counted. Older versions only log `token_count` events, which are re-emitted with unchanged totals — only events whose running total moved are counted.
+- **Cached tokens are inside `input_tokens`.** Codex reports cached reads and cache writes as parts of `input_tokens`, and reasoning tokens as part of `output_tokens`. Billable uncached input is `input − cached − cache_write`; reasoning is never added on top.
+- **Its own cost source.** Codex spend is priced directly from its logs and is never replaced by, or scaled with, Claude Code's statusline-hook figures.
+- **Compressed rollouts.** Codex compresses older rollouts to `.jsonl.zst`. Python's standard library only reads zstd from 3.14, so on older Pythons cctrack uses the `zstd` command if it's installed, and otherwise skips those files and says how many it skipped.
+
+Costs are at OpenAI's **API list prices**. If you use Codex through a ChatGPT plan, that's an API-equivalent value, not what you're billed — the same is true of Claude Code on a Claude subscription.
+
+## 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.
+
+```bash
+# Aggregate this machine + DGX server + laptop
+cctrack --remote dgx macbook-air
+
+# For accurate aggregate costs, install the hook on each host too
+cctrack --install-hook --remote dgx macbook-air
+```
+
+## Rate card
+
+Prices per million tokens. Claude prices are from [Anthropic's pricing page](https://platform.claude.com/docs/en/about-claude/pricing); cache writes are priced per TTL (5-minute and 1-hour).
+
+| Claude model | Input | Output | Cache Read | Cache Write 5m | Cache Write 1h |
+|---|---|---|---|---|---|
+| Fable 5.1 / Mythos 5.1 | $10.00 | $50.00 | $0.25 | $12.50 | $20.00 |
+| Fable 5 / Mythos 5 | $10.00 | $50.00 | $1.00 | $12.50 | $20.00 |
+| Opus 5.5 | $4.00 | $20.00 | $0.20 | $5.00 | $8.00 |
+| Opus 5 / 4.8 / 4.7 / 4.6 / 4.5 | $5.00 | $25.00 | $0.50 | $6.25 | $10.00 |
+| Opus 4.1 / 4 | $15.00 | $75.00 | $1.50 | $18.75 | $30.00 |
+| Sonnet 5.5 | $2.00 | $10.00 | $0.10 | $2.50 | $4.00 |
+| Sonnet 5 | $2.00 | $10.00 | $0.20 | $2.50 | $4.00 |
+| Sonnet 4.6 / 4.5 / 4 / 3.7 | $3.00 | $15.00 | $0.30 | $3.75 | $6.00 |
+| Haiku 5.5 (prompt ≤ 100K) | $0.10 | $0.50 | $0.01 | $0.125 | $0.20 |
+| Haiku 5.5 (prompt > 100K) | $0.50 | $2.50 | $0.05 | $0.625 | $1.00 |
+| Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 | $2.00 |
+| Haiku 3.5 | $0.80 | $4.00 | $0.08 | $1.00 | $1.60 |
+| Haiku 3 | $0.25 | $1.25 | $0.03 | $0.30 | $0.50 |
+
+OpenAI prices (for Codex) are from [OpenAI's pricing page](https://developers.openai.com/api/docs/pricing), Standard tier. OpenAI has a single cache-write price, listed only for some models; elsewhere cache writes bill as ordinary input.
+
+| OpenAI model | Input | Cached input | Output | Cache write | Over 272K input |
+|---|---|---|---|---|---|
+| gpt-6-astra | $10.00 | $1.00 | $50.00 | $12.50 | $20 / $2 / $75 / $25 |
+| gpt-6.1-sol | $2.00 | $0.10 | $10.00 | $2.50 | $4 / $0.20 / $15 / $5 |
+| gpt-6-sol | $2.00 | $0.20 | $10.00 | $2.50 | $4 / $0.40 / $15 / $5 |
+| gpt-6-luna | $0.10 | $0.01 | $0.50 | $0.125 | $0.20 / $0.02 / $0.75 / $0.25 |
+| gpt-5.6-sol | $4.00 | $0.40 | $20.00 | $5.00 | $8 / $0.80 / $30 / $10 |
+| gpt-5.6-terra | $2.00 | $0.20 | $12.00 | $2.50 | $4 / $0.40 / $18 / $5 |
+| gpt-5.6-luna | $0.20 | $0.02 | $1.20 | $0.25 | $0.40 / $0.04 / $1.80 / $0.50 |
+| gpt-5.5 | $5.00 | $0.50 | $30.00 | — | $10 / $1 / $45 |
+| gpt-5.5-pro / gpt-5.4-pro | $30.00 | — | $180.00 | — | $60 / — / $270 |
+| gpt-5.4 | $2.50 | $0.25 | $15.00 | — | $5 / $0.50 / $22.50 |
+| gpt-5.4-mini | $0.75 | $0.075 | $4.50 | — | |
+| gpt-5.4-nano | $0.20 | $0.02 | $1.25 | — | |
+| gpt-5.3-codex / gpt-5.2 | $1.75 | $0.175 | $14.00 | — | |
+| gpt-5.2-pro | $21.00 | — | $168.00 | — | |
+| gpt-5.1 / gpt-5 | $1.25 | $0.125 | $10.00 | — | |
+| gpt-5-pro | $15.00 | — | $120.00 | — | |
+| gpt-5-mini | $0.25 | $0.025 | $2.00 | — | |
+| gpt-5-nano | $0.05 | $0.005 | $0.40 | — | |
+
+Codex variants without their own price (e.g. `gpt-5.1-codex`) are priced as their base model, consistent with the one variant OpenAI does list (`gpt-5.3-codex` = `gpt-5.2`). Long-context and Haiku 5.5 prompt-length tiers are applied per request.
+
+**Every model version has its own row.** A model only matches a row if it is that version or a dated snapshot of it — never a newer minor version. So a newly released model (say `claude-opus-5-7`, or `gpt-5.1-codex-mini`) shows as unknown and is flagged with `?` in the Model column, rather than silently inheriting its predecessor's price. Unknown Claude models are estimated at Sonnet rates, unknown OpenAI models at GPT-5 rates. Pricing is date-aware, so any time-limited introductory price applies only to usage on the days it was in effect.
+
+## Energy estimate
+
+`cctrack --energy` adds an estimated inference energy column (Wh/kWh):
+
+```bash
+cctrack --energy
+```
+
+This is a **rough estimate, not a measurement** — Anthropic does not publish per-token energy figures or model sizes. It is modelled from logged tokens using the published full-stack per-prompt figures the major labs have disclosed (Google: 0.24 Wh median Gemini text prompt; OpenAI: ~0.34 Wh average ChatGPT query — both include accelerator, host, cooling and idle capacity), apportioned across token classes by relative compute cost and scaled by model tier:
+
+- **output tokens dominate** — decode is sequential and memory-bandwidth bound
+- **input and cache writes** are prefill: parallel, far cheaper per token
+- **cache reads** skip prefill entirely (~0.1× input)
+- both cache-write TTLs use the same figure — a 1-hour write costs more money but the same compute
+
+Treat results as ±1 order of magnitude. It covers datacenter inference only: not model training, and not your own machine. Scale the whole model with `CCTRACK_ENERGY_SCALE=1.5` if you have better numbers for your workload.
+
+## Origins
+
+This is a Python rewrite of the Go-based [cctrack dashboard](https://github.com/ksred/cctrack). The Go version provides a full web dashboard with real-time updates, session explorer, and project breakdown. This Python version strips it down to the essentials: a single command that parses logs and prints a cost report. The JSONL parsing logic, deduplication strategy, and rate card are ported directly from the Go implementation.
+
+## License
+
+[MIT](LICENSE)

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

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

cctrack-0.8.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())