cctrack 0.8.0__tar.gz → 0.10.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cctrack-0.8.0 → cctrack-0.10.0}/CLAUDE.md +5 -4
- {cctrack-0.8.0 → cctrack-0.10.0}/PKG-INFO +36 -4
- {cctrack-0.8.0 → cctrack-0.10.0}/README.md +35 -3
- {cctrack-0.8.0 → cctrack-0.10.0}/pyproject.toml +1 -1
- {cctrack-0.8.0 → cctrack-0.10.0}/src/cctrack/__init__.py +1111 -73
- cctrack-0.10.0/tests/conftest.py +25 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/tests/test_codex.py +1 -1
- cctrack-0.10.0/tests/test_detail.py +303 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/tests/test_hook_reporting.py +21 -13
- cctrack-0.10.0/tests/test_sandy.py +298 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/.github/workflows/ci.yml +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/.github/workflows/publish.yml +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/.gitignore +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/LICENSE +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/scripts/diagnose_session_cost.py +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/scripts/trace_project.py +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/src/cctrack/__main__.py +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/tests/test_cctrack.py +0 -0
- {cctrack-0.8.0 → cctrack-0.10.0}/tests/test_hook.py +0 -0
|
@@ -33,14 +33,15 @@ This is a single-module CLI tool. All logic lives in `src/cctrack/__init__.py`:
|
|
|
33
33
|
|
|
34
34
|
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.
|
|
35
35
|
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.
|
|
36
|
-
2. **File discovery** (`default_dirs`, `discover_files`) -
|
|
37
|
-
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"`.
|
|
38
|
-
3. **Remote aggregation** (`fetch_remote_jsonl`, `parse_remote_events`, `fetch_remote_hook_data`, `parse_remote_hook_data`) -
|
|
36
|
+
2. **File discovery** (`sandy_home`, `_sandy_print_state`, `sandbox_roots`, `default_dirs`, `discover_files`) - Claude transcripts from `~/.claude/projects/` plus each Sandy sandbox's `claude/projects/` (ONLY `projects/` — `claude/` also holds `history.jsonl`, job timelines, tool-audit logs). Sandbox roots come from `sandy --print-state` → `sandboxes[].path` (follows `$SANDY_HOME`), else `$SANDY_HOME/sandboxes/*` (default `~/.sandy`). Per sandy's host-side path contract each root has agent homes `claude/` (→ `~/.claude` in the sandbox) and `codex/` (→ `~/.codex`); everything else under a root is private. **Dot-entries** (`_is_sandbox_name`): skip `.rsync-from.*` (an in-progress `sandy --rsync-from` copy — its hook data was being summed twice) and `*.lock`; any other dot-dir is a REAL sandbox iff it holds `WORKSPACE.json` (a workspace like `~/.dotfiles` → sandbox `.dotfiles-<sha8>`). Sandy's own enumeration, hence `--print-state`, currently omits dot-named sandboxes, so they're always added by scanning `sandboxes/` directly. Tests are isolated from real sandboxes by `tests/conftest.py`.
|
|
37
|
+
2a. **Codex** (`codex_homes`, `discover_codex_files`, `parse_codex_lines`, `parse_codex_events`, `fetch_remote_codex`) - Reads `$CODEX_HOME` (default `~/.codex`) and every sandbox's `codex/` (sandy never sets CODEX_HOME), `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"`.
|
|
38
|
+
3. **Remote aggregation** (`remote_sandbox_roots`, `fetch_remote_jsonl`, `parse_remote_events`, `fetch_remote_hook_data`, `parse_remote_hook_data`, `fetch_remote_codex`) - One SSH call per host finds its sandbox roots (same rules as locally, cached), then each fetch cats the host's own dirs plus the matching per-sandbox dirs with file separators and parses locally.
|
|
39
39
|
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.
|
|
40
40
|
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.
|
|
41
41
|
5. **Aggregation** (`aggregate`) - Buckets events into daily and monthly summaries with token counts and costs.
|
|
42
|
-
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.
|
|
42
|
+
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; when unmeasurable, `DEFAULT_ACCURACY_FACTOR` is **1.0** — the old 1.25 "logs undercount ~20-25%" was entirely rate-card error and inflated unmeasured days 25%.
|
|
43
43
|
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.
|
|
44
|
+
6b. **Detailed reports** (`run_detail_report`, `build_session_rows`, `build_bucket_rows`, `build_coverage`, `build_document`, `write_csv`; flags `--sessions --bucket --coverage --json --csv --since --until --redact --billing-mode`) - Everything UTC; `--since/--until` are a half-open window and are rejected without one of these views. Session key = (agent, host, sandbox, session id, subagent id): Claude sidechain turns (`isSidechain`, `agentId`, else the `agent-<id>.jsonl` filename) are separate rows linked to the parent sessionId; Codex threads use the record's `thread_id` (a fork's replayed records stay with the parent) and get a parent from `session_meta` (`source…parent_thread_id`, `forked_from_id`, or `session_id` ≠ `id`). Parsers fill per-file stats (`new_parse_stats`: lines, unparseable lines, records, timestamp range, compactions keyed by marker so resume replays don't double count) only when asked. Remote streams carry each file's path after the separator. Hook cost is day-granular, so it's attached only for day-aligned windows. Output is ids/paths/counts/money only; `SCHEMA_VERSION` must be bumped on any breaking field change.
|
|
44
45
|
|
|
45
46
|
Entry point: `cctrack:main` (registered in `pyproject.toml` as a console script).
|
|
46
47
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: cctrack
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.10.0
|
|
4
4
|
Summary: Claude Code cost tracker — scans JSONL logs and reports token usage + estimated cost
|
|
5
5
|
Project-URL: Homepage, https://github.com/rappdw/cctrack
|
|
6
6
|
Project-URL: Repository, https://github.com/rappdw/cctrack
|
|
@@ -50,7 +50,7 @@ cctrack --days 7
|
|
|
50
50
|
cctrack --remote dgx macbook-air
|
|
51
51
|
|
|
52
52
|
# Custom log directories
|
|
53
|
-
cctrack --dirs ~/.claude/projects
|
|
53
|
+
cctrack --dirs ~/.claude/projects ~/old-machine/projects
|
|
54
54
|
|
|
55
55
|
# Only one coding agent (default: all found)
|
|
56
56
|
cctrack --agent claude
|
|
@@ -82,7 +82,7 @@ Daily breakdown:
|
|
|
82
82
|
|
|
83
83
|
## What it does
|
|
84
84
|
|
|
85
|
-
1. Walks `~/.claude/projects/` and
|
|
85
|
+
1. Walks `~/.claude/projects/` — and each [Sandy](#sandy-sandboxes) sandbox's `claude/projects/` — for Claude Code transcripts, and each Codex home for Codex rollouts
|
|
86
86
|
2. Parses `assistant` events with token usage
|
|
87
87
|
3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
|
|
88
88
|
4. Calculates cost using Anthropic's published rates per model
|
|
@@ -90,7 +90,7 @@ Daily breakdown:
|
|
|
90
90
|
|
|
91
91
|
## Codex CLI
|
|
92
92
|
|
|
93
|
-
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.
|
|
93
|
+
cctrack also reads [Codex CLI](https://github.com/openai/codex) usage from `$CODEX_HOME` (default `~/.codex`) and from every [Sandy sandbox](#sandy-sandboxes)'s `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.
|
|
94
94
|
|
|
95
95
|
How it's counted (verified against the Codex source, not inferred):
|
|
96
96
|
|
|
@@ -101,6 +101,18 @@ How it's counted (verified against the Codex source, not inferred):
|
|
|
101
101
|
|
|
102
102
|
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.
|
|
103
103
|
|
|
104
|
+
## Sandy sandboxes
|
|
105
|
+
|
|
106
|
+
cctrack finds every [Sandy](https://github.com/rappdw/sandy) sandbox on the machine (and on `--remote` hosts) and includes its Claude Code and Codex usage. It follows sandy's published host-side path contract:
|
|
107
|
+
|
|
108
|
+
- **Finding sandboxes:** `sandy --print-state` (`sandboxes[].path`) when sandy is installed, which follows `$SANDY_HOME`; otherwise `$SANDY_HOME/sandboxes/*` (default `~/.sandy/sandboxes`).
|
|
109
|
+
- **Per sandbox:** Claude Code transcripts from `claude/projects/`, statusline-hook data from `claude/cctrack/`, Codex rollouts from `codex/sessions/` and `codex/archived_sessions/`. Other files under `claude/` (`history.jsonl`, job timelines, tool-audit logs) aren't transcripts and are ignored.
|
|
110
|
+
- **Never double counted:** the hidden `.rsync-from.<name>.<pid>/` copy that exists while `sandy --rsync-from` is pulling a sandbox in is skipped, as are `.lock` directories. A sandbox's Codex home is never shared with the host's `~/.codex`, and anything copied between hosts with `sandy --rsync` is deduplicated by request/response id.
|
|
111
|
+
|
|
112
|
+
- **Dot-named sandboxes count:** a workspace named like a dotfile directory (e.g. `~/.dotfiles`) gets a sandbox whose name starts with a dot. Sandy's own listing currently omits these, so cctrack scans for them itself — any dot-directory holding `WORKSPACE.json` is a real sandbox.
|
|
113
|
+
|
|
114
|
+
Orphaned sandboxes (workspace deleted, sandbox not yet removed) still count: their usage is real history.
|
|
115
|
+
|
|
104
116
|
## Explore a day
|
|
105
117
|
|
|
106
118
|
When a day's cost looks wrong or surprisingly high, `--explore` breaks it down:
|
|
@@ -127,6 +139,26 @@ cctrack --explore 2026-08-03 --project team-inbox
|
|
|
127
139
|
|
|
128
140
|
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.
|
|
129
141
|
|
|
142
|
+
## Sessions, time buckets and coverage (JSON / CSV)
|
|
143
|
+
|
|
144
|
+
For attributing cost to sessions, roles or time windows. All times and day boundaries are **UTC**; output holds ids, paths, counts and money only, never prompt or response content.
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
cctrack --sessions --since 2026-10-11T02:30:04Z --until 2026-10-12 # per-session table
|
|
148
|
+
cctrack --bucket hour --since 2026-10-11 --until 2026-10-12 # cost per UTC hour
|
|
149
|
+
cctrack --coverage # what data exists, and gaps
|
|
150
|
+
cctrack --json --since 2026-10-11 > report.json # everything, one document
|
|
151
|
+
cctrack --csv sessions # or buckets | coverage | rates
|
|
152
|
+
cctrack --json --redact # hash paths and names
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
- `--since` / `--until` take ISO-8601 (zones converted to UTC; naive times are UTC) or `YYYY-MM-DD`. The window is `since <= t < until`, and a bare `--until` date includes that whole day.
|
|
156
|
+
- **Sessions**: one row per session, with Claude subagent (sidechain) turns as their own rows linked by `parent_session_id`. Codex subagent threads are separate sessions that carry their parent's id. Each row has agent, host, Sandy sandbox, project/cwd, git branch, first and last record time, models, request count, tokens and cost in five classes (input, output, cache read, 5-minute and 1-hour cache write), mean and max cache-read and context tokens per request, and compactions.
|
|
157
|
+
- **Cost basis**: `cost_usd` is always API list price from the built-in rate card. The rates applied (per model, $/Mtok per class), the card's version and its sources are in the JSON (`rate_card`, `cost_basis`) and in `--csv rates`. For Claude, `hook_cost_usd` is Claude Code's own cost counter. It's booked per UTC day, so it's only filled in for day-aligned windows. Logs don't say whether you're on API or subscription billing, so record that with `--billing-mode subscription` (or `claude=subscription,codex=api`, or `CCTRACK_BILLING_MODE`). It's shown on each row and doesn't change cost.
|
|
158
|
+
- **Coverage**: for each log directory (per host and sandbox), the file count, usage records, earliest and latest timestamp, and any unparseable lines or unreadable files (status `UNKNOWN`). Days in the window with no records are listed as UNKNOWN, since idle days and lost logs look the same. Where the statusline hook saw Claude spend but no transcript exists, the day and session are flagged with tokens UNKNOWN. That's the signature of lost logs.
|
|
159
|
+
- `--redact` hashes cwd, project, sandbox, branch and file paths, but not session ids. Set `CCTRACK_REDACT_SALT` so the hashes of guessable repo names can't be reversed.
|
|
160
|
+
- JSON and CSV carry `schema_version` (currently 1). Field names are stable within a schema version.
|
|
161
|
+
|
|
130
162
|
## Remote aggregation
|
|
131
163
|
|
|
132
164
|
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.
|
|
@@ -25,7 +25,7 @@ cctrack --days 7
|
|
|
25
25
|
cctrack --remote dgx macbook-air
|
|
26
26
|
|
|
27
27
|
# Custom log directories
|
|
28
|
-
cctrack --dirs ~/.claude/projects
|
|
28
|
+
cctrack --dirs ~/.claude/projects ~/old-machine/projects
|
|
29
29
|
|
|
30
30
|
# Only one coding agent (default: all found)
|
|
31
31
|
cctrack --agent claude
|
|
@@ -57,7 +57,7 @@ Daily breakdown:
|
|
|
57
57
|
|
|
58
58
|
## What it does
|
|
59
59
|
|
|
60
|
-
1. Walks `~/.claude/projects/` and
|
|
60
|
+
1. Walks `~/.claude/projects/` — and each [Sandy](#sandy-sandboxes) sandbox's `claude/projects/` — for Claude Code transcripts, and each Codex home for Codex rollouts
|
|
61
61
|
2. Parses `assistant` events with token usage
|
|
62
62
|
3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
|
|
63
63
|
4. Calculates cost using Anthropic's published rates per model
|
|
@@ -65,7 +65,7 @@ Daily breakdown:
|
|
|
65
65
|
|
|
66
66
|
## Codex CLI
|
|
67
67
|
|
|
68
|
-
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.
|
|
68
|
+
cctrack also reads [Codex CLI](https://github.com/openai/codex) usage from `$CODEX_HOME` (default `~/.codex`) and from every [Sandy sandbox](#sandy-sandboxes)'s `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.
|
|
69
69
|
|
|
70
70
|
How it's counted (verified against the Codex source, not inferred):
|
|
71
71
|
|
|
@@ -76,6 +76,18 @@ How it's counted (verified against the Codex source, not inferred):
|
|
|
76
76
|
|
|
77
77
|
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.
|
|
78
78
|
|
|
79
|
+
## Sandy sandboxes
|
|
80
|
+
|
|
81
|
+
cctrack finds every [Sandy](https://github.com/rappdw/sandy) sandbox on the machine (and on `--remote` hosts) and includes its Claude Code and Codex usage. It follows sandy's published host-side path contract:
|
|
82
|
+
|
|
83
|
+
- **Finding sandboxes:** `sandy --print-state` (`sandboxes[].path`) when sandy is installed, which follows `$SANDY_HOME`; otherwise `$SANDY_HOME/sandboxes/*` (default `~/.sandy/sandboxes`).
|
|
84
|
+
- **Per sandbox:** Claude Code transcripts from `claude/projects/`, statusline-hook data from `claude/cctrack/`, Codex rollouts from `codex/sessions/` and `codex/archived_sessions/`. Other files under `claude/` (`history.jsonl`, job timelines, tool-audit logs) aren't transcripts and are ignored.
|
|
85
|
+
- **Never double counted:** the hidden `.rsync-from.<name>.<pid>/` copy that exists while `sandy --rsync-from` is pulling a sandbox in is skipped, as are `.lock` directories. A sandbox's Codex home is never shared with the host's `~/.codex`, and anything copied between hosts with `sandy --rsync` is deduplicated by request/response id.
|
|
86
|
+
|
|
87
|
+
- **Dot-named sandboxes count:** a workspace named like a dotfile directory (e.g. `~/.dotfiles`) gets a sandbox whose name starts with a dot. Sandy's own listing currently omits these, so cctrack scans for them itself — any dot-directory holding `WORKSPACE.json` is a real sandbox.
|
|
88
|
+
|
|
89
|
+
Orphaned sandboxes (workspace deleted, sandbox not yet removed) still count: their usage is real history.
|
|
90
|
+
|
|
79
91
|
## Explore a day
|
|
80
92
|
|
|
81
93
|
When a day's cost looks wrong or surprisingly high, `--explore` breaks it down:
|
|
@@ -102,6 +114,26 @@ cctrack --explore 2026-08-03 --project team-inbox
|
|
|
102
114
|
|
|
103
115
|
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.
|
|
104
116
|
|
|
117
|
+
## Sessions, time buckets and coverage (JSON / CSV)
|
|
118
|
+
|
|
119
|
+
For attributing cost to sessions, roles or time windows. All times and day boundaries are **UTC**; output holds ids, paths, counts and money only, never prompt or response content.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
cctrack --sessions --since 2026-10-11T02:30:04Z --until 2026-10-12 # per-session table
|
|
123
|
+
cctrack --bucket hour --since 2026-10-11 --until 2026-10-12 # cost per UTC hour
|
|
124
|
+
cctrack --coverage # what data exists, and gaps
|
|
125
|
+
cctrack --json --since 2026-10-11 > report.json # everything, one document
|
|
126
|
+
cctrack --csv sessions # or buckets | coverage | rates
|
|
127
|
+
cctrack --json --redact # hash paths and names
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- `--since` / `--until` take ISO-8601 (zones converted to UTC; naive times are UTC) or `YYYY-MM-DD`. The window is `since <= t < until`, and a bare `--until` date includes that whole day.
|
|
131
|
+
- **Sessions**: one row per session, with Claude subagent (sidechain) turns as their own rows linked by `parent_session_id`. Codex subagent threads are separate sessions that carry their parent's id. Each row has agent, host, Sandy sandbox, project/cwd, git branch, first and last record time, models, request count, tokens and cost in five classes (input, output, cache read, 5-minute and 1-hour cache write), mean and max cache-read and context tokens per request, and compactions.
|
|
132
|
+
- **Cost basis**: `cost_usd` is always API list price from the built-in rate card. The rates applied (per model, $/Mtok per class), the card's version and its sources are in the JSON (`rate_card`, `cost_basis`) and in `--csv rates`. For Claude, `hook_cost_usd` is Claude Code's own cost counter. It's booked per UTC day, so it's only filled in for day-aligned windows. Logs don't say whether you're on API or subscription billing, so record that with `--billing-mode subscription` (or `claude=subscription,codex=api`, or `CCTRACK_BILLING_MODE`). It's shown on each row and doesn't change cost.
|
|
133
|
+
- **Coverage**: for each log directory (per host and sandbox), the file count, usage records, earliest and latest timestamp, and any unparseable lines or unreadable files (status `UNKNOWN`). Days in the window with no records are listed as UNKNOWN, since idle days and lost logs look the same. Where the statusline hook saw Claude spend but no transcript exists, the day and session are flagged with tokens UNKNOWN. That's the signature of lost logs.
|
|
134
|
+
- `--redact` hashes cwd, project, sandbox, branch and file paths, but not session ids. Set `CCTRACK_REDACT_SALT` so the hashes of guessable repo names can't be reversed.
|
|
135
|
+
- JSON and CSV carry `schema_version` (currently 1). Field names are stable within a schema version.
|
|
136
|
+
|
|
105
137
|
## Remote aggregation
|
|
106
138
|
|
|
107
139
|
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.
|