/agent-cost-report

name: Agent Cost Report
description: >-
  Believable agent cost report for any period, default the last 7 full days PT, not counting today.
  Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured
  provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus
  report.json, line-items.csv, evidence.json.
allowed-tools:
  - Bash
  - Read
  - Write
  - AskUserQuestion
  - mcp__plugin_claude-mem_mcp-search__search
  - mcp__plugin_claude-mem_mcp-search__timeline
  - mcp__plugin_claude-mem_mcp-search__get_observations

Agent Cost Report

**Claude-Mem / Claude Code skill.** Runtime is the `scripts/` pipeline (transcripts → tokens → dollars → Timing-style report) plus a progressive Mem Search review pass that confirms the drafted labels. The Notion draft is SPEC history only — never the product, never the runtime, never the ship vehicle.

Resolve the absolute directory containing this `SKILL.md`; all helper paths are relative to that directory. `${CLAUDE_SKILL_DIR}` is the shortcut: `python3 "${CLAUDE_SKILL_DIR}/scripts/acr.py" …`. Python 3.9+ standard library only; no pip installs. The look lives in `scripts/acr/render.py`, never here.

Purpose

Turn Claude-Mem activity into a **manager-readable cost and failure report**.

Product idea: a reusable skill that searches Claude-Mem via Mem Search, reconstructs real units of work, assigns cost and failure categories, and renders a printable report.

Insight north star

The headline is dollars, to two decimals, labeled. The dollars come from Claude Code transcripts (exact per-reply token usage) priced at OpenRouter public list prices, so they are **ESTIMATED**. Measured provider spend appears only when a sanctioned source gives it. Directly under the dollars: what the mistakes cost, what shipped, and both on one time axis.

Questions the report must answer

1. What work was completed? 2. What did each outcome cost? 3. What was wasted through looping, hedging, wrong turns, rework, or poor routing? 4. Were any unauthorized actions attempted? 5. What should the manager change next?

**Primary unit = cost per completed outcome** (not cost per observation).

When to use

• "Agent cost report" / "cost per outcome" / "failure economics" / "was this session worth it" / "what did the agents cost this week"
• After a real Mem session dig when leadership needs outcome economics
• Sample / ship packs that need self-contained HTML + JSON + CSV + evidence

Memory dig mechanics: the claude-mem `mem-search` skill (progressive recall).

Default scope (ALWAYS)

• Unless the user names a **specific session / range / project**, the window is the **last 7 full days in PT, not counting today**: `end` = the PT midnight that started today (exclusive), `start` = `end − 7 days`. The default window never contains a partial day (G3, Alex 2026-09-25).
• Explicit windows: `--start YYYY-MM-DD --end YYYY-MM-DD` (PT calendar days, end exclusive). An explicit `--end` later than today marks the last day "partial, generated HH:MM PT".
• One session: `--session <content_session_id>`. One project plus a period: `--project <name> --start … --end …` (worktrees of the project are included).
• The report **Scope** strip shows the PT range, and Details list every session id in scope.

Progressive Mem Search (ALWAYS)

Follow the claude-mem `mem-search` three layers. Keep spend light.

1. **Search** — get an index of IDs (titles, types, token hints). 2. **Timeline** — only around anchors you care about. 3. **Observations** — `get_observations` for the filtered IDs you will cite as evidence.

Recipe:

1. Resolve scope (default: the last 7 full PT days). 2. Search → collect IDs. 3. Timeline for thin context only. 4. Observations for intended / actual / outcome / waste / rework / blocked / unauthorized / status. 5. Group into named work items + failure events. 6. Calculate line-item costs. 7. Render HTML + optional PDF (+ json/csv/evidence). 8. Keep evidence IDs in the appendix — do not dump entire timelines into the main report.

ADHD process bullets:

• Search first → pick IDs → timeline only if context is thin → fetch only needed obs.
• Work-item titles are invented for managers ("Restore search after Chroma crash-loop"); observation titles stay evidence-only.
• Evidence appendix lists obs IDs + short titles; main sections stay outcome-first.

In this skill the search pass is the **review step** (see Recipe step 4): the pipeline drafts categories and failure types from keywords (`label_source: keyword`); the orchestrator confirms or changes each line item's `category` and `failure_type` from its cited evidence IDs and applies the result with `review --apply`. Items left unreviewed keep the "draft label" mark and the footer counts them.

Work categories (ALWAYS)

`Feature` · `Bug fix` · `Incident` · `Maintenance` · `Investigation` · `Experiment`

Failure / waste types (ALWAYS)

`Looping` · `Hedging` · `Wrong turn` · `Rework` · `Regression` · `Premature completion` · `Unauthorized action` · `Suboptimal path` · `Duplicate work` · `Blocked work` · `Missed requirement` · `Unnecessary escalation` · `Context re-read` · `Model thrash` · `Fan-out waste` · `Recovery after miss`

**Rework lock (ALWAYS):** Rework lives **only** under `failure_type` — never as a work category. Keep category as the intended job type; set `failure_type: Rework` when rework occurred.

A line item can have a work category **and** a failure_type (e.g. Maintenance + Looping).

Cost model

Measured tokens come from Claude Code transcripts (`~/.claude/projects/**/*.jsonl`, assistant replies deduped on `(message.id, requestId)`); Codex transcripts are read the same way. Prices are OpenRouter public list prices per million tokens, fetched at run time and saved with the report.

agent_cost_i (per reply, micro-dollars) =
      input × price.input + output × price.output
    + cache_write_5m × price.cache_write