Skip to content
Get packs

Guide · Agent skill

How to use the Agent Cost Report agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

Agent Cost Report is a skill for Claude Code and Claude-Mem that turns a period of agent activity into a manager-style cost and waste report. This guide covers what the skill does, how to install it from the ZIP or the Claude apps, how to ask for a report in plain language, and what it needs and touches on your machine. After reading it you should be able to run a report and understand which figures are estimates.

Agent Cost Reportthedotmack/claude-mem · Apache-2.0

Quick start

  1. 1Download the ZIP. Download the Agent Cost Report ZIP from this page.
  2. 2Install the skill. Unzip into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
  3. 3Check prerequisites. Confirm Python 3.9+ is available and that Claude Code transcripts exist in ~/.claude/projects.
  4. 4Ask for a report. Say "agent cost report" for the default last 7 full PT days, or name a date range, session or project.
  5. 5Approve any install prompt. If the script reports missing timezone data, review the lines it prints and approve or decline installing tzdata.
  6. 6Review the output. Open the HTML or PDF report and check the ESTIMATED labels, draft labels and evidence IDs.

What does the Agent Cost Report skill make the agent do?

When the skill is installed, the agent can produce a cost report of Claude Code and Claude-Mem activity for a chosen period. By default that period is the last 7 full Pacific days, not counting today. The agent reads local Claude Code transcript files, counts tokens per reply, estimates dollar cost using OpenRouter public list prices, and groups work into outcomes with cost and waste labels.

The output is an HTML or PDF report plus JSON, CSV and evidence files. Dollar figures are labelled as estimates, not provider bills.

  • Work categories: Feature, Bug fix, Incident, Maintenance, Investigation, Experiment.
  • Waste types include Looping, Hedging, Wrong turn, Rework, Regression and Blocked work.
  • Headline cost is shown to two decimals and labelled ESTIMATED.

How do you install the Agent Cost Report skill?

There are two routes. For Claude Code, download the ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into .claude/skills/ inside a project if you want it limited to that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

After installing, check that the folder contains SKILL.md and a scripts/ directory with acr.py. The skill's own instructions say to use the directory that contains SKILL.md as the base for all helper paths.

  • Route 1: download the ZIP, unzip into ~/.claude/skills/ (user-wide) or .claude/skills/ (per project).
  • Route 2: in the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.

What does the skill need before it runs?

The core pipeline needs Python 3.9 or newer, using only the standard library. It also needs IANA timezone data for America/Los_Angeles. Claude Code transcripts must exist in ~/.claude/projects. For the review pass that confirms labels, Claude-Mem with its mem-search MCP tools must be available.

An OpenRouter API key is optional and only used for the optional classifier pass (--classify). The source says it needs a regular inference key only.

  • Python 3.9+ (standard library only).
  • Timezone data for America/Los_Angeles; the tzdata package is only installed after you approve it, and only if the system lacks timezone data (stock Windows Python often does).
  • Claude Code transcripts in ~/.claude/projects.
  • Claude-Mem with mem-search MCP tools for the review step.
  • Optional: OpenRouter API key for --classify.

How do you ask the agent for a report?

You do not need a command. Ask in plain language and the agent will pick the scope. Phrases the skill is written to respond to include "agent cost report", "cost per outcome", "failure economics", "was this session worth it" and "what did the agents cost this week".

To narrow the scope, name a session, a date range or a project. The skill accepts explicit windows as PT calendar days with the end date exclusive, for example --start YYYY-MM-DD --end YYYY-MM-DD. For one session it uses --session with a content session id.

  • Default: "agent cost report" with no dates gives the last 7 full PT days.
  • Date range: "agent cost report for 2026-09-01 to 2026-09-08" maps to explicit --start and --end values.
  • One session: give the content session id to use --session.
  • One project: name the project and period to use --project with --start and --end.
python3 "${CLAUDE_SKILL_DIR}/scripts/acr.py" --start YYYY-MM-DD --end YYYY-MM-DD

How do you read the report?

The headline is dollars, labelled as estimated. They come from Claude Code transcripts priced at OpenRouter list prices, so they are not measured provider spend. Measured provider spend appears only when a sanctioned source provides it. Directly under the dollars, the report shows what the mistakes cost and what shipped, on one time axis.

The primary unit is cost per completed outcome, not cost per observation. Work-item titles are written for managers, while evidence IDs appear in an appendix.

  • ESTIMATED: priced from transcript tokens at list prices.
  • EXTRAPOLATED: used for sessions with no transcript on this machine; low confidence.
  • Draft label: a line item the review step has not yet confirmed.
  • Note-taker (observer) cost is priced separately and never counted as agent cost.

What does the skill touch on your machine?

The skill runs scripts and uses the network. It reads conversation history from local Claude Code transcripts, so transcripts may contain sensitive content that ends up in the report. The source says the report can be exported as HTML, PDF, JSON, CSV and evidence files, so review those files before sharing them.

Prices are fetched from OpenRouter public list prices at run time and saved with the report. The only package the skill may install is tzdata, and only after you approve it.

  • Read: ~/.claude/projects transcript files (including Codex transcripts, per the source).
  • Network: fetches OpenRouter public list prices at run time.
  • Install: tzdata only, only on approval and only if timezone data is missing.
  • Output: HTML or PDF plus report.json, line-items.csv and evidence.json.
  • Do not run it on environments where transcripts hold content you do not want processed or exported.

What people use it for

  • A engineering lead gets a rough cost-per-outcome view of a week of Claude Code work.
  • A developer using Claude-Mem sees where tokens were looped, hedged or spent on wrong turns.
  • A team prints a weekly summary of agent work for a review meeting.
  • A manager checks whether a single Claude Code session was worth its cost by naming the session id.

Frequently asked questions

Is the Agent Cost Report skill free?

The source gives the licence as Apache-2.0. It does not list a price for the skill itself. The dollar figures it produces are estimates from OpenRouter public list prices.

What does the Agent Cost Report skill require?

It requires Python 3.9 or newer using only the standard library, timezone data for America/Los_Angeles, Claude Code transcripts in ~/.claude/projects, and Claude-Mem with mem-search MCP tools for the review pass. An OpenRouter key is optional for the --classify pass.

How do I install the Agent Cost Report skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Are the dollar figures exact provider bills?

No. The report labels dollars as ESTIMATED, calculated from transcript token counts and OpenRouter list prices. The source says it is not for exact billing or invoice reconciliation.

Why does the skill say it cannot find timezone data?

Stock Windows Python often ships without IANA timezone data. The skill then asks before installing tzdata. Setting the PYTHONTZPATH environment variable instead needs no install, according to the source.

Does the skill send my transcripts anywhere?

The source says the skill reads conversation history and uses the network, and it fetches OpenRouter list prices at run time. It does not say transcripts are uploaded, but reports can contain transcript-derived content, so check outputs before sharing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Agent Cost Report if you are an engineering lead or a Claude Code and Claude-Mem user who wants a rough, labelled view of cost per outcome and wasted turns, and you are comfortable with Python and local transcripts. Pick something else if you need exact billing or invoice reconciliation, or if your transcripts hold content you cannot have processed or exported.

Download the skill