Cost

---
name: cost
description: Session and month-to-date cost from transcripts — cost completed sessions, read the anchored budget, explain where the money went. Only active when the cost module is enabled (cost.enabled in agenticos.json after `aos cost enable`); otherwise explain how to enable it. Use when the user asks "how much did this cost", "cost the last session", "what's my spend this month", "$agenticos:cost", or "backfill costs".
---
<!-- generated by tools/build-codex-plugin.js from plugin/; edit the source there, not this file -->

> Host: Codex CLI, through the `agenticos` plugin. Invoke as `$agenticos:cost`. `<plugin root>` is the plugin's folder, two levels above the folder that holds this SKILL.md; the `aos` launcher is `<plugin root>/bin/aos`. The tools of the `agenticos` MCP server are named `mcp__agenticos__<tool>`.

# Cost

The cost module is opt-in. **First** read `cost.enabled` in
`${CLAUDE_CONFIG_DIR:-~/.claude}/agenticos.json`.

- **Disabled or absent** → answer: the cost module is off; enabling it needs python3 ≥ 3.9 and one command, `aos cost enable [--budget <usd>]` (it copies the transcript analyzer into `<vault>/brain/scripts/cost/`, flips the flag, and records the monthly budget in `brain/config.json`). Then stop. Do not estimate costs by hand.
- **Enabled** → continue.

## What exists

- `auto-cost` runs at every session end and patches `cost_usd` (with `cost_source`) into `brain/_index/agent-runs/runs.jsonl`, by the run's host: a Codex session's transcript under `<claudeConfigDir>/projects/*/<session>.jsonl` goes through the analyzer; a Codex session's rollout under `<codex home>/sessions/**/rollout-*.jsonl` is priced from its final token count (no analyzer, no python3). The pipeline ledger (`brain/_index/pipelines.json`, `auto-cost`) shows `ok`, `skipped` (no transcript), `disabled` (cost is off — `aos cost disable`, or never enabled), or `error` (analyzer failed).
- `aos auto-cost --backfill` costs every completed session that still has `cost_usd: null`; `aos auto-cost --cost-one <session-uuid>` costs one.
- `aos cost-budget` prints the anchored month-to-date: a real billed figure anchored at a point in time plus calibrated transcript costs for sessions that ended since. `aos cost-budget --anchor <usd>` re-anchors to a fresh billed number; `--budget <usd>` changes the monthly budget.
- Headless provider spend (the `claude` or `codex` provider's own calls) is separate: `aos status` shows today's hook spend against the resolved provider's cap (`claude.perDayUsd` or `codex.perDayUsd`) and the persona's duty spend (`duty:*` ledger rows) against `persona.perDayUsd`, one line each, plus the reasoner, routines and graph lines. Codex reports tokens, never dollars, so every Codex figure is an estimate from its token counts.

## Answering

1. For "what did session X cost": Bash `aos auto-cost --cost-one <uuid>` (fallback `sh "<plugin root>/bin/aos" …`), then read that run's row in `runs.jsonl` and report `cost_usd`.
2. For "how much this month": `aos cost-budget`; report month-to-date, the budget, and the anchor date.
3. For "where did it go": the analyzer's per-turn breakdown is in its `--out` JSON (path printed by `auto-cost`); the largest entries are usually large tool results and big file writes, not named skills — say so rather than blaming a skill bucket.
4. Transcript-derived costs exclude the platform's hidden baseline: a slight, consistent underestimate. Say so once when reporting a total.


## The `$agenticos:cost` procedure

Cost sessions. First read `cost.enabled` in `${CLAUDE_CONFIG_DIR:-~/.claude}/agenticos.json`.

- If it is `false` or absent: tell the user the cost module is off and how to turn it on — `aos cost enable` (needs python3 ≥ 3.9) — and stop.
- If a session UUID was given: Bash `aos auto-cost --cost-one <uuid>` (fallback: `sh "<plugin root>/bin/aos" auto-cost --cost-one <uuid>`). The script finds the session by its host — a Claude Code transcript under `<claudeConfigDir>/projects/*/<uuid>.jsonl` (priced by the analyzer) or a Codex rollout under `<codex home>/sessions/` (priced from its token count) — and patches `cost_usd` in `brain/_index/agent-runs/runs.jsonl`. Do not target the live session; it is not finalized yet.
- Otherwise: `aos auto-cost --backfill` costs every completed session that still has `cost_usd: null` and a transcript on disk.

Report the sessions costed and the headline USD. Costs are transcript-derived and exclude the platform baseline, so they are a slight, consistent underestimate (Codex figures are token-count estimates); `aos cost-budget` shows the anchored month-to-date figure and `aos cost-budget --anchor <usd>` recalibrates it to a billed number.