reflect:cost

# /reflect:cost — Drain spend report

Shows what the reflect background drainer is spending: token volume split into
**cached** (cheap reuse), **uncached writes** (expensive cache_creation), and
**io** (input+output), plus a ballpark `$est`, grouped by day, outcome, model,
or transcript. This is the observability the 2026-05-31 incident lacked — one
drain run burned 41.5M tokens / ~$713 for zero net-new learnings and nothing
surfaced it until a manual backfill.

## When to Use

- "What did reflection cost me today / this week?"
- Spot an outlier run (a single transcript that blew up the spend).
- Check **cache reuse**: a healthy drain is cache_read-heavy; a low cache-reuse
  % with high cache_creation is the costly failure mode.
- Confirm the drain is running on the cheap model (should be `sonnet`, not
  `opus`) after a deploy.

## Window argument

Parse the window from the user's request and pass it as `--since`:

| User says | `--since` |
|-----------|-----------|
| "1 day", "today", "last 24h", (default) | `1d` |
| "this week", "last 7 days" | `7d` |
| "last hour" | `1h` |
| "last month", "30 days" | `30d` |

Default to `1d` when unspecified.

## Run it

Locate the cost reporter (prefer the running plugin, else the newest cached
version), then render. The script is `reflect_cost.py`, shipped in the reflect
plugin's `scripts/`.

```bash
WINDOW="1d"   # ← substitute from the table above

# Resolve reflect_cost.py robustly across deploy layouts.
COST_PY=""
for cand in \
  "${CLAUDE_PLUGIN_ROOT:-}/scripts/reflect_cost.py" \
  $(ls -t "$HOME"/.claude/plugins/cache/agents-in-a-box/reflect/*/scripts/reflect_cost.py 2>/dev/null); do
  if [ -n "$cand" ] && [ -f "$cand" ]; then COST_PY="$cand"; break; fi
done
if [ -z "$COST_PY" ]; then
  echo "reflect_cost.py not found — install/update the reflect plugin (v4+):"
  echo "  claude plugin update reflect@agents-in-a-box"
  exit 1
fi

# Headline: by outcome (where the spend goes), then model (cheap vs expensive),
# then the top transcripts (find the outlier).
python3 "$COST_PY" --since "$WINDOW" --by outcome
echo
python3 "$COST_PY" --since "$WINDOW" --by model
echo
python3 "$COST_PY" --since "$WINDOW" --by transcript --top 10
```

For a machine-readable view, add `--json`.

## If tokens show 0 (historical / pre-v4 events)

The drainer only began recording the full token envelope in v4. Older cost
events carry only `outcome` (no tokens/model), so the split shows `0`.
Reconstruct the real numbers from the raw session logs with the backfill — it
scans `~/.claude/projects`, finds the reflect runs, and sums their usage into a
separate `drain-cost-backfill.jsonl` (which `reflect_cost.py` reads alongside
the live log):

```bash
BACKFILL_PY="$(dirname "$COST_PY")/backfill_costs.py"
python3 "$BACKFILL_PY" --since "$WINDOW" \
  --projects-dir "$HOME/.claude/projects" \
  --state-dir "${REFLECT_STATE_DIR:-$HOME/.reflect}"
# then re-run the reflect_cost.py commands above
```

## Reading the output

```
outcome                 runs    tokens  cache_rd  cache_wr      io     $est
ok                        48      120M       95M       18M     7.0M   220.40
partial_max_turns          3       40M       30M        8M     2.0M    70.10
```

- **cache_rd** (cache_read) — cheap reuse, *should* dominate.
- **cache_wr** (cache_creation) — expensive writes; high here means caching is
  not amortizing (re-paying to rebuild context). The incident was cache_wr-heavy.
- **io** — input + output tokens.
- **$est** — authoritative `cost_usd` from `claude -p` where recorded, else an
  order-of-magnitude estimate from token buckets × ballpark list prices. Not a bill.
- **⚠ outlier** — any single run above `--outlier-tokens` (default 5M). One
  flagged transcript is usually where a spend spike lives.
- The **cache-reuse %** line at the bottom is the fastest health read: low % +
  high cache_wr = the 41.5M failure mode.

Then summarize for the user in one or two lines: total tokens, the cached vs
uncached split, the model, the $est, and call out any outlier transcript.

## Troubleshooting

- **"reflect_cost.py not found"** — the installed plugin predates v4. Run
  `claude plugin update reflect@agents-in-a-box` and restart.
- **All rows show model `?` and 0 tokens** — pre-v4 events only; run the
  backfill above.
- **No events at all** — the drain hasn't run in the window, or
  `REFLECT_STATE_DIR` points elsewhere (`ls "${REFLECT_STATE_DIR:-$HOME/.reflect}"`).