costcut CLI

OSS CLI for Costcut. Tracks Claude Code session tokens, cost, hook compliance.

Backward compatibility: binary alias cost-guard also 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):

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