cctrack 0.9.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.9.0 → cctrack-0.10.0}/CLAUDE.md +1 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/PKG-INFO +21 -1
- {cctrack-0.9.0 → cctrack-0.10.0}/README.md +20 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/pyproject.toml +1 -1
- {cctrack-0.9.0 → cctrack-0.10.0}/src/cctrack/__init__.py +907 -37
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/test_codex.py +1 -1
- cctrack-0.10.0/tests/test_detail.py +303 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/.github/workflows/ci.yml +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/.github/workflows/publish.yml +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/.gitignore +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/LICENSE +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/scripts/diagnose_session_cost.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/scripts/trace_project.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/src/cctrack/__main__.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/conftest.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/test_cctrack.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/test_hook.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/test_hook_reporting.py +0 -0
- {cctrack-0.9.0 → cctrack-0.10.0}/tests/test_sandy.py +0 -0
|
@@ -41,6 +41,7 @@ This is a single-module CLI tool. All logic lives in `src/cctrack/__init__.py`:
|
|
|
41
41
|
5. **Aggregation** (`aggregate`) - Buckets events into daily and monthly summaries with token counts and costs.
|
|
42
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
|
|
@@ -139,6 +139,26 @@ cctrack --explore 2026-08-03 --project team-inbox
|
|
|
139
139
|
|
|
140
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.
|
|
141
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
|
+
|
|
142
162
|
## Remote aggregation
|
|
143
163
|
|
|
144
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.
|
|
@@ -114,6 +114,26 @@ cctrack --explore 2026-08-03 --project team-inbox
|
|
|
114
114
|
|
|
115
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.
|
|
116
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
|
+
|
|
117
137
|
## Remote aggregation
|
|
118
138
|
|
|
119
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.
|