Metadata-Version: 2.4
Name: costcut
Version: 0.0.9
Summary: Claude Code observability + cost optimization CLI
Project-URL: Homepage, https://costcut.dev
Project-URL: Repository, https://github.com/kuznetsov-ai/cost-guard
Author-email: Eugene Kuznetsov <eugene@costcut.dev>
License: MIT
Keywords: claude-code,cost,llm,observability,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# cost-guard CLI

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

## Install (Week 6+)

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

## Dev install

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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)
<!-- delegation-guard: ok -->

- `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

```bash
cd cli
pytest                                              # 50 tests, ~1s
COSTGUARD_REAL_SMOKE=1 pytest tests/test_real_data_smoke.py  # opt-in: scans real ~/.claude/projects
```

<!-- delegation-guard: ok -->
