costcut CLI
OSS CLI for Costcut. Tracks Claude Code session tokens, cost, hook compliance.
Backward compatibility: binary alias
cost-guardalso works for the main commands.
Install (Week 6+)
pip install costcut # PyPI (Week 6 release)
brew install costcut # Homebrew tap (Week 6 release)
Dev install
cd cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
costcut --version
Commands
costcut init — install hooks bundle (Week 3 ✅)
Installs 5 bundled hook scripts + shared library into .claude/hooks/, registers them in .claude/settings.json.
cost-guard init # install to .claude/hooks (default)
cost-guard init --target ~/.claude/hooks # explicit target path
cost-guard init --dry-run # preview changes, write nothing
cost-guard init --force # overwrite existing hooks
Installs:
- Hooks:
parallel_agents_guard.sh,test_before_push_guard.sh,large_read_warning.sh,token_alert.sh,session_cost_check.sh - Library:
_lib/cost.sh(shared utilities)
Registers hooks in .claude/settings.json with event + matcher + command path. Idempotent: running twice adds no duplicates.
Exit code 0 on success, 1 on error.
costcut report — session analytics (Week 2 ✅)
Scans Claude Code JSONL transcripts in ~/.claude/projects/, aggregates tokens + cost per session, renders a Rich table.
costcut report # default: last 20 sessions for cwd
costcut report --project ~/Projects/MyApp # specific project
costcut report --since 2026-05-01 # only sessions since date
costcut report --last 5 # top 5 most recent
costcut report --all # no limit
Output columns: Started | Duration | Model | Msgs | In | Out | Cache | Cost | Session. Final row = TOTAL.
costcut auth — token management (Week 7 ✅)
Manages authentication with backend API.
costcut auth set <api_key> # save API key (must start with cg_live_)
costcut auth status # check login status + show masked token
costcut auth logout # remove stored token
Token storage: ~/.config/costcut/token (0o600 permissions). Env override: COSTCUT_TOKEN=cg_live_... takes precedence. Backend: GET /v1/auth/me (Bearer JWT).
costcut push — upload sessions to backend (Week 7 ✅)
Aggregates sessions from local JSONL and POSTs to backend API.
costcut push # default: last 30 days
costcut push --project ~/Projects/MyApp # specific project
costcut push --since 7 # only last 7 days
costcut push --dry-run # preview without HTTP
Requires authenticated token. Filters by --since (days). POSTs {id, project, primary_model, started_at, ended_at, input_tokens, output_tokens, cost_usd}. Continues on errors, returns 1 if any failed.
Stubs (later weeks)
costcut live— real-time TUI dashboard (Week 2.5)costcut alert --budget 5— daily spend cap (Week 3)
Pricing
Per-million-token rates (verified 2026-05-23 against https://docs.claude.com/en/docs/about-claude/models):
| Model | Input | Output | Cache read | Cache write 5m | Cache write 1h |
|---|---|---|---|---|---|
claude-opus-4-7 / 4-6 |
$15 | $75 | $1.50 | $18.75 | $30 |
claude-sonnet-4-6 / 4-5 |
$3 | $15 | $0.30 | $3.75 | $6 |
claude-haiku-4-5 |
$1 | $5 | $0.10 | $1.25 | $2 |
Unknown models return cost=0 (not None) — see cost_guard.pricing.compute_cost_usd.
Tests
cd cli
pytest # 50 tests, ~1s
COSTGUARD_REAL_SMOKE=1 pytest tests/test_real_data_smoke.py # opt-in: scans real ~/.claude/projects
Metadata
Release files for costcut 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| costcut-0.1.0.tar.gz | 40.7 kB | Without provenance | Details for costcut-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| costcut-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for costcut-0.1.0-py3-none-any.whl |
Total release size: 77.1 kB
Release files / costcut-0.1.0.tar.gz
| Download URL | costcut-0.1.0.tar.gz |
|---|---|
| Size | 40.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92f348133332db166e86713f9fc1cc2e0bdf711a8f448b98bb6fd8235803a5e8
|
|
BLAKE2b-256 checksum How to use checksums |
5130aa04f28e88db38467101fbe19bc1a21d2d0ad8ccd76c861e4fee08ab7fbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / costcut-0.1.0-py3-none-any.whl
| Download URL | costcut-0.1.0-py3-none-any.whl |
|---|---|
| Size | 36.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f34940c6b0791f7162b9970476216168cba1a77f3a03afccac4ad712bc4c0d54
|
|
BLAKE2b-256 checksum How to use checksums |
0697e7ccd166f01048bc02fa634c1335a960d25899b81dccf755c84983244e88
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for costcut 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.