Metadata-Version: 2.4
Name: costcut
Version: 0.1.0
Summary: Claude Code observability + cost optimization CLI
Project-URL: Homepage, https://costcut.dev
Author-email: Costcut Team <team@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: bench
Requires-Dist: tiktoken>=0.7.0; extra == 'bench'
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'
Requires-Dist: tiktoken>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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+)

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

```bash
pip install costcut         # PyPI (Week 6 release)
brew install costcut        # Homebrew tap (Week 6 release)
```

## Dev install

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

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

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

### `costcut report` — session analytics (Week 2 ✅)

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

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

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

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

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