---
name: cost-tracker
description: Record or summarise LLM / service spend in the JSONL ledger. Auto-invoke when the user asks about "cost", "spend", "budget", "how much did X cost".
allowed-tools: Bash(hexa cost *)
---

# cost-tracker

Every paid LLM / TTS / image / search call should be funnelled through the
cost ledger. Budget discipline is enforced by the S4 universal invariant.

## Record an entry

```bash
hexa cost track \
  --project-id "$PROJECT_ID" \
  --stage research \
  --service anthropic \
  --operation generate \
  --cost 0.0123 \
  --model claude-sonnet-4-5 \
  --tokens-in 4200 --tokens-out 870
```

## Summarise

```bash
# total for the project
hexa cost summary --project-id "$PROJECT_ID"

# per-stage breakdown
hexa cost summary --project-id "$PROJECT_ID" --stage research
```

## Integration

Wire the tracker into every LLM client wrapper. `hexa_swarm_core.llm.base`
ships a `safe_generate` helper that records automatically — prefer that over
hand-rolled retry loops.

## Relationship to S4

`hexa_swarm_core.safety.CostCeiling.check_can_spend(...)` reads the same
ledger. If a call would breach the project's ceiling, it raises
`SafetyViolationError(invariant="S4")` **before** the spend happens.