ainb fleet:cost
Fleet-shaped spend rollups. ainb already tracks cost_usd per provider call
(the burndown plugin aggregates it); this verb reshapes that data into
per-session / per-model / per-day / per-group USD totals joined to the live
fleet, and evaluates configured budget caps.
Run
ainb fleet cost # text tables (default)
ainb --format json fleet cost # JSON for piping
ainb --format json fleet cost --period week # window: today|week|30days|month|all
--format is a global flag — it goes before fleet, not after cost.
The --period window scopes the data (default month): burndown date-bounds
its call set and re-aggregates, so a narrower period returns less spend; all
reports lifetime totals.
Output fields (JSON)
| field |
meaning |
totals |
fleet-wide {cost_usd, bucket, session_count, model_count} |
sessions[] |
per-session {session_id, provider, project, cwd?, group?, cost_usd, bucket}, sorted by descending cost |
models[] |
per-model {model, cost_usd, bucket}, sorted by descending cost |
daily[] |
per-day {date, cost_usd, bucket} |
groups[] |
per-workspace {group, cost_usd, session_count, bucket} (only sessions that match a live fleet cwd) |
budget_breaches[] |
{scope, subject, cwd?, cost_usd, limit_usd} — caps crossed this run (also delivered to notifyd) |
bucket is the token breakdown: input_tokens, cache_creation_tokens,
cache_read_tokens, output_tokens, reasoning_tokens, call_count,
cost_usd.
Budget caps
Configure spend ceilings in config.toml (project config overrides user
config). A breach fires a notifyd alert (Notification:budget_exceeded,
surfacing as WaitingOnUser) and lands in notifications.db.
[fleet.cost]
session_usd = 5.0 # warn when any single session crosses $5
group_usd = 25.0 # warn when any workspace group crosses $25
[fleet.cost.session_overrides]
"abc123" = 50.0 # a long-running session gets its own ceiling
[fleet.cost.group_overrides]
"infra" = 100.0 # the infra workspace gets a higher ceiling
Override maps take precedence over the blanket session_usd / group_usd.
With no caps configured, budget_breaches is always empty.
Composition patterns
# Most expensive session
ainb --format json fleet cost | jq '.sessions[0]'
# Total spend this month
ainb --format json fleet cost | jq '.totals.cost_usd'
# Any budget breaches right now?
ainb --format json fleet cost | jq '.budget_breaches'
# Spend by group, biggest first
ainb --format json fleet cost | jq '.groups[] | {group, cost_usd}'
Caveats
- Cost data is sourced live from the burndown plugin. The first call on a
cold cache can take
40s while session-reader scans `/.claude/projects; raise the budget with AINB_USAGE_TIMEOUT_SECS=` for very large
archives. Subsequent calls hit the cache and return in well under a second.
- The
group on a session is only populated when its resolved cwd matches
a session in the live fleet (via workspace_name). Sessions that have
ended drop out of the group rollup but still appear in sessions[].
- Budget alert delivery is best-effort: if notifyd's socket is unreachable
the command still prints the report (with a warning on stderr).
- This verb never re-prices anything — it relies entirely on ainb's existing
pricing. To change pricing or plan, use
ainb usage plan ....
1---2name: ainb-fleet-cost3description: |4 Show fleet spend — per-session, per-model, per-day, and per-group USD5 cost rollups for every claude/codex session, sourced live from ainb's6 burndown analytics (which already prices every provider call). Use when7 you need spend visibility across a multi-session fleet, want to find the8 most expensive session/model, or are checking whether any session/group9 has crossed a configured budget cap. Budget breaches are also delivered10 as notifyd alerts.11 Default output: text tables. Pass --format json for LLM consumption.12version: "0.1.0"13user-invocable: true14triggers:15 - ainb-fleet:cost16 - fleet cost17 - fleet spend18 - how much have my sessions cost19 - which session is most expensive20 - fleet budget21allowed-tools:22 - Bash23metadata:24 source: https://skillmd.com/skills/stevengonsalvez/ainb-fleet-cost25---2627# ainb fleet:cost2829Fleet-shaped spend rollups. ainb already tracks `cost_usd` per provider call30(the burndown plugin aggregates it); this verb reshapes that data into31per-session / per-model / per-day / per-group USD totals joined to the live32fleet, and evaluates configured budget caps.3334## Run3536```bash37ainb fleet cost # text tables (default)38ainb --format json fleet cost # JSON for piping39ainb --format json fleet cost --period week # window: today|week|30days|month|all40```4142`--format` is a **global** flag — it goes before `fleet`, not after `cost`.43The `--period` window scopes the data (default `month`): burndown date-bounds44its call set and re-aggregates, so a narrower period returns less spend; `all`45reports lifetime totals.4647## Output fields (JSON)4849| field | meaning |50|---|---|51| `totals` | fleet-wide `{cost_usd, bucket, session_count, model_count}` |52| `sessions[]` | per-session `{session_id, provider, project, cwd?, group?, cost_usd, bucket}`, sorted by descending cost |53| `models[]` | per-model `{model, cost_usd, bucket}`, sorted by descending cost |54| `daily[]` | per-day `{date, cost_usd, bucket}` |55| `groups[]` | per-workspace `{group, cost_usd, session_count, bucket}` (only sessions that match a live fleet cwd) |56| `budget_breaches[]` | `{scope, subject, cwd?, cost_usd, limit_usd}` — caps crossed this run (also delivered to notifyd) |5758`bucket` is the token breakdown: `input_tokens`, `cache_creation_tokens`,59`cache_read_tokens`, `output_tokens`, `reasoning_tokens`, `call_count`,60`cost_usd`.6162## Budget caps6364Configure spend ceilings in `config.toml` (project config overrides user65config). A breach fires a notifyd alert (`Notification:budget_exceeded`,66surfacing as `WaitingOnUser`) and lands in `notifications.db`.6768```toml69[fleet.cost]70session_usd = 5.0 # warn when any single session crosses $571group_usd = 25.0 # warn when any workspace group crosses $257273[fleet.cost.session_overrides]74"abc123" = 50.0 # a long-running session gets its own ceiling7576[fleet.cost.group_overrides]77"infra" = 100.0 # the infra workspace gets a higher ceiling78```7980Override maps take precedence over the blanket `session_usd` / `group_usd`.81With no caps configured, `budget_breaches` is always empty.8283## Composition patterns8485```bash86# Most expensive session87ainb --format json fleet cost | jq '.sessions[0]'8889# Total spend this month90ainb --format json fleet cost | jq '.totals.cost_usd'9192# Any budget breaches right now?93ainb --format json fleet cost | jq '.budget_breaches'9495# Spend by group, biggest first96ainb --format json fleet cost | jq '.groups[] | {group, cost_usd}'97```9899## Caveats100101- Cost data is sourced live from the burndown plugin. The first call on a102 cold cache can take ~40s while session-reader scans `~/.claude/projects`;103 raise the budget with `AINB_USAGE_TIMEOUT_SECS=<n>` for very large104 archives. Subsequent calls hit the cache and return in well under a second.105- The `group` on a session is only populated when its resolved `cwd` matches106 a session in the live fleet (via `workspace_name`). Sessions that have107 ended drop out of the group rollup but still appear in `sessions[]`.108- Budget alert delivery is best-effort: if notifyd's socket is unreachable109 the command still prints the report (with a warning on stderr).110- This verb never re-prices anything — it relies entirely on ainb's existing111 pricing. To change pricing or plan, use `ainb usage plan ...`.