costcut 0.0.9

Claude Code observability + cost optimization CLI

cost-guard CLI

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

Install (Week 6+)

pip install cost-guard      # PyPI (Week 6 release)
brew install cost-guard     # Homebrew tap (Week 6 release)

Dev install

cd cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
cost-guard --version

Commands

cost-guard 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.

cost-guard report — session analytics (Week 2 ✅)

Scans Claude Code JSONL transcripts in ~/.claude/projects/, aggregates tokens + cost per session, renders a Rich table.

cost-guard report                                   # default: last 20 sessions for cwd
cost-guard report --project ~/Projects/MyApp        # specific project
cost-guard report --since 2026-05-01                # only sessions since date
cost-guard report --last 5                          # top 5 most recent
cost-guard report --all                             # no limit

Output columns: Started | Duration | Model | Msgs | In | Out | Cache | Cost | Session. Final row = TOTAL.

cost-guard auth — token management (Week 7 ✅)

Manages authentication with backend API.

cost-guard auth set <api_key>                      # save API key (must start with cg_live_)
cost-guard auth status                              # check login status + show masked token
cost-guard auth logout                              # remove stored token

Token storage: ~/.config/cost-guard/token (0o600 permissions). Env override: COST_GUARD_TOKEN=cg_live_... takes precedence. Backend: GET /v1/auth/me (Bearer JWT).

cost-guard push — upload sessions to backend (Week 7 ✅)

Aggregates sessions from local JSONL and POSTs to backend API.

cost-guard push                                     # default: last 30 days
cost-guard push --project ~/Projects/MyApp          # specific project
cost-guard push --since 7                           # only last 7 days
cost-guard 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)

• cost-guard live — real-time TUI dashboard (Week 2.5)
• cost-guard 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