cctrack 0.1.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.
Files changed (11) hide show
  1. cctrack-0.1.0/.github/workflows/ci.yml +31 -0
  2. cctrack-0.1.0/.github/workflows/publish.yml +67 -0
  3. cctrack-0.1.0/.gitignore +9 -0
  4. cctrack-0.1.0/CLAUDE.md +48 -0
  5. cctrack-0.1.0/LICENSE +21 -0
  6. cctrack-0.1.0/PKG-INFO +116 -0
  7. cctrack-0.1.0/README.md +91 -0
  8. cctrack-0.1.0/pyproject.toml +36 -0
  9. cctrack-0.1.0/src/cctrack/__init__.py +342 -0
  10. cctrack-0.1.0/src/cctrack/__main__.py +3 -0
  11. cctrack-0.1.0/tests/test_cctrack.py +620 -0
cctrack-0.1.0/.github/workflows/ci.yml ADDED
@@ -0,0 +1,31 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python ${{ matrix.python-version }}
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+
24
+ - name: Install package
25
+ run: pip install -e .
26
+
27
+ - name: Install test dependencies
28
+ run: pip install pytest
29
+
30
+ - name: Run tests
31
+ run: python -m pytest tests/ -v
cctrack-0.1.0/.github/workflows/publish.yml ADDED
@@ -0,0 +1,67 @@
1
+ name: Release to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ id-token: write
9
+
10
+ jobs:
11
+ build:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Set up Python
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+
21
+ - name: Install build tools
22
+ run: pip install build
23
+
24
+ - name: Build package
25
+ run: python -m build
26
+
27
+ - name: Upload artifacts
28
+ uses: actions/upload-artifact@v4
29
+ with:
30
+ name: dist
31
+ path: dist/
32
+
33
+ test:
34
+ runs-on: ubuntu-latest
35
+ strategy:
36
+ matrix:
37
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+
41
+ - name: Set up Python ${{ matrix.python-version }}
42
+ uses: actions/setup-python@v5
43
+ with:
44
+ python-version: ${{ matrix.python-version }}
45
+
46
+ - name: Install package
47
+ run: pip install -e .
48
+
49
+ - name: Install test dependencies
50
+ run: pip install pytest
51
+
52
+ - name: Run tests
53
+ run: python -m pytest tests/ -v
54
+
55
+ publish:
56
+ needs: [build, test]
57
+ runs-on: ubuntu-latest
58
+ environment: pypi
59
+ steps:
60
+ - name: Download artifacts
61
+ uses: actions/download-artifact@v4
62
+ with:
63
+ name: dist
64
+ path: dist/
65
+
66
+ - name: Publish to PyPI
67
+ uses: pypa/gh-action-pypi-publish@release/v1
cctrack-0.1.0/.gitignore ADDED
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .pytest_cache/
8
+ .venv/
9
+ *.whl
cctrack-0.1.0/CLAUDE.md ADDED
@@ -0,0 +1,48 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ cctrack-py is a zero-dependency Python CLI that scans Claude Code JSONL 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.
8
+
9
+ ## Commands
10
+
11
+ ```bash
12
+ # Install in development mode
13
+ uv pip install -e .
14
+
15
+ # Run the tool
16
+ python -m cctrack
17
+ # or after install:
18
+ cctrack
19
+
20
+ # Run all tests
21
+ python -m pytest tests/
22
+
23
+ # Run a single test
24
+ python -m pytest tests/test_cctrack.py::test_name
25
+
26
+ # Build distribution
27
+ uv build
28
+ ```
29
+
30
+ ## Architecture
31
+
32
+ This is a single-module CLI tool. All logic lives in `src/cctrack/__init__.py`:
33
+
34
+ 1. **Rate card** (`RATES`, `get_rates`, `calculate_cost`) - Model-to-price mapping using prefix matching. Order matters: longer/more-specific prefixes must come first. Unknown models fall back to Sonnet rates.
35
+ 2. **File discovery** (`default_dirs`, `discover_files`) - Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for `.jsonl` files.
36
+ 3. **Remote aggregation** (`fetch_remote_jsonl`, `parse_remote_events`) - SSHs to hosts, cats all JSONL with file separators, parses locally. Each file chunk gets independent dedup.
37
+ 4. **JSONL parsing** (`parse_lines`, `parse_events`) - Extracts `assistant` events with token usage. Deduplicates by `requestId` per file (last event wins), matching Claude Code's semantics. Events without `requestId` are never deduped.
38
+ 5. **Aggregation** (`aggregate`) - Buckets events into daily and monthly summaries with token counts and costs.
39
+ 6. **Output** (`print_report`) - Prints current month-to-date summary with projections, daily breakdown, and previous month summaries.
40
+
41
+ Entry point: `cctrack:main` (registered in `pyproject.toml` as a console script).
42
+
43
+ ## Key Design Decisions
44
+
45
+ - Zero external dependencies - stdlib only (json, argparse, subprocess, etc.)
46
+ - Deduplication is per-file, not global - same `requestId` in different files produces separate entries
47
+ - Build system is Hatch (`hatchling`)
48
+ - Requires Python 3.10+
cctrack-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dan Rapp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
cctrack-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,116 @@
1
+ Metadata-Version: 2.4
2
+ Name: cctrack
3
+ Version: 0.1.0
4
+ Summary: Claude Code cost tracker — scans JSONL logs and reports token usage + estimated cost
5
+ Project-URL: Homepage, https://github.com/ksred/cctrack
6
+ Project-URL: Repository, https://github.com/ksred/cctrack
7
+ Project-URL: Issues, https://github.com/ksred/cctrack/issues
8
+ Author: Dan Rapp
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: anthropic,claude,claude-code,cost,tokens
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Software Development :: Quality Assurance
22
+ Classifier: Topic :: System :: Monitoring
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+
26
+ # cctrack
27
+
28
+ A lightweight CLI tool that scans [Claude Code](https://docs.anthropic.com/en/docs/claude-code) JSONL logs and reports token usage and estimated cost. Zero dependencies, runs anywhere Python 3.10+ is available.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ # Run directly (no install needed)
34
+ uvx cctrack
35
+
36
+ # Or install globally
37
+ uv tool install cctrack
38
+ ```
39
+
40
+ ## Usage
41
+
42
+ ```bash
43
+ # Scan local logs and print report
44
+ cctrack
45
+
46
+ # Last 7 days only
47
+ cctrack --days 7
48
+
49
+ # Aggregate with remote machines via SSH
50
+ cctrack --remote dgx macbook-air
51
+
52
+ # Custom log directories
53
+ cctrack --dirs ~/.claude/projects ~/.sandy/sandboxes
54
+ ```
55
+
56
+ ## Example output
57
+
58
+ ```
59
+ cctrack — Claude Code Cost Report
60
+ ══════════════════════════════════
61
+
62
+ April 2026 — month to date (day 1, 1 active)
63
+ ───────────────────────────────────────
64
+ Input tokens: 23,381
65
+ Output tokens: 199,069
66
+ Cache read: 30,862,977
67
+ Cache write: 1,051,023
68
+ Total tokens: 32,136,450
69
+ Total cost: $25.85
70
+ Avg/day: $25.85
71
+ Projected/mo: $775.50 (based on 1-day avg)
72
+
73
+ Daily breakdown:
74
+ Date Input Output Cache R Cache W Cost
75
+ ──────────── ──────────── ──────────── ──────────── ──────────── ──────────
76
+ 2026-04-01 23,381 199,069 30,862,977 1,051,023 $ 25.85
77
+ ```
78
+
79
+ ## What it does
80
+
81
+ 1. Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for JSONL log files
82
+ 2. Parses `assistant` events with token usage
83
+ 3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
84
+ 4. Calculates cost using Anthropic's published rates per model
85
+ 5. Prints daily breakdown with input/output/cache token splits and monthly summaries
86
+
87
+ ## Remote aggregation
88
+
89
+ With `--remote`, cctrack SSHs to each host (one call per host) and streams back all JSONL content for local parsing. Requires SSH key auth.
90
+
91
+ ```bash
92
+ # Aggregate this machine + DGX server + laptop
93
+ cctrack --remote dgx macbook-air
94
+ ```
95
+
96
+ ## Rate card
97
+
98
+ Prices per million tokens, from [Anthropic's pricing page](https://www.anthropic.com/pricing):
99
+
100
+ | Model | Input | Output | Cache Read | Cache Write |
101
+ |---|---|---|---|---|
102
+ | Opus 4.6 / 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
103
+ | Opus 4 / 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
104
+ | Sonnet 4.x | $3.00 | $15.00 | $0.30 | $3.75 |
105
+ | Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 |
106
+ | Haiku 3.x | $0.80 | $4.00 | $0.08 | $1.00 |
107
+
108
+ Unknown models fall back to Sonnet rates.
109
+
110
+ ## Origins
111
+
112
+ 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.
113
+
114
+ ## License
115
+
116
+ [MIT](LICENSE)
cctrack-0.1.0/README.md ADDED
@@ -0,0 +1,91 @@
1
+ # cctrack
2
+
3
+ A lightweight CLI tool that scans [Claude Code](https://docs.anthropic.com/en/docs/claude-code) JSONL logs and reports token usage and estimated cost. Zero dependencies, runs anywhere Python 3.10+ is available.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ # Run directly (no install needed)
9
+ uvx cctrack
10
+
11
+ # Or install globally
12
+ uv tool install cctrack
13
+ ```
14
+
15
+ ## Usage
16
+
17
+ ```bash
18
+ # Scan local logs and print report
19
+ cctrack
20
+
21
+ # Last 7 days only
22
+ cctrack --days 7
23
+
24
+ # Aggregate with remote machines via SSH
25
+ cctrack --remote dgx macbook-air
26
+
27
+ # Custom log directories
28
+ cctrack --dirs ~/.claude/projects ~/.sandy/sandboxes
29
+ ```
30
+
31
+ ## Example output
32
+
33
+ ```
34
+ cctrack — Claude Code Cost Report
35
+ ══════════════════════════════════
36
+
37
+ April 2026 — month to date (day 1, 1 active)
38
+ ───────────────────────────────────────
39
+ Input tokens: 23,381
40
+ Output tokens: 199,069
41
+ Cache read: 30,862,977
42
+ Cache write: 1,051,023
43
+ Total tokens: 32,136,450
44
+ Total cost: $25.85
45
+ Avg/day: $25.85
46
+ Projected/mo: $775.50 (based on 1-day avg)
47
+
48
+ Daily breakdown:
49
+ Date Input Output Cache R Cache W Cost
50
+ ──────────── ──────────── ──────────── ──────────── ──────────── ──────────
51
+ 2026-04-01 23,381 199,069 30,862,977 1,051,023 $ 25.85
52
+ ```
53
+
54
+ ## What it does
55
+
56
+ 1. Walks `~/.claude/projects/` and `~/.sandy/sandboxes/` for JSONL log files
57
+ 2. Parses `assistant` events with token usage
58
+ 3. Deduplicates by `requestId` (last event wins, matching Claude Code's semantics)
59
+ 4. Calculates cost using Anthropic's published rates per model
60
+ 5. Prints daily breakdown with input/output/cache token splits and monthly summaries
61
+
62
+ ## Remote aggregation
63
+
64
+ With `--remote`, cctrack SSHs to each host (one call per host) and streams back all JSONL content for local parsing. Requires SSH key auth.
65
+
66
+ ```bash
67
+ # Aggregate this machine + DGX server + laptop
68
+ cctrack --remote dgx macbook-air
69
+ ```
70
+
71
+ ## Rate card
72
+
73
+ Prices per million tokens, from [Anthropic's pricing page](https://www.anthropic.com/pricing):
74
+
75
+ | Model | Input | Output | Cache Read | Cache Write |
76
+ |---|---|---|---|---|
77
+ | Opus 4.6 / 4.5 | $5.00 | $25.00 | $0.50 | $6.25 |
78
+ | Opus 4 / 4.1 | $15.00 | $75.00 | $1.50 | $18.75 |
79
+ | Sonnet 4.x | $3.00 | $15.00 | $0.30 | $3.75 |
80
+ | Haiku 4.5 | $1.00 | $5.00 | $0.10 | $1.25 |
81
+ | Haiku 3.x | $0.80 | $4.00 | $0.08 | $1.00 |
82
+
83
+ Unknown models fall back to Sonnet rates.
84
+
85
+ ## Origins
86
+
87
+ 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.
88
+
89
+ ## License
90
+
91
+ [MIT](LICENSE)
cctrack-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,36 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "cctrack"
7
+ version = "0.1.0"
8
+ description = "Claude Code cost tracker — scans JSONL logs and reports token usage + estimated cost"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ { name = "Dan Rapp" },
14
+ ]
15
+ keywords = ["claude", "anthropic", "cost", "tokens", "claude-code"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Environment :: Console",
19
+ "Intended Audience :: Developers",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Topic :: Software Development :: Quality Assurance",
27
+ "Topic :: System :: Monitoring",
28
+ ]
29
+
30
+ [project.scripts]
31
+ cctrack = "cctrack:main"
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/ksred/cctrack"
35
+ Repository = "https://github.com/ksred/cctrack"
36
+ Issues = "https://github.com/ksred/cctrack/issues"