A local cost and setup audit for Claude Code. Point it at your session logs and it shows where token spend leaks, scores your setup across six pillars, and ranks counterfactual opportunities by estimated token value.

Your prompts are analyzed locally and never uploaded. The audit parses the logs already on your disk and prints a report.

Use it

Requires Node 20+.

npx costclaw audit

That reads ~/.claude/projects (override with --path <dir>) and prints a local report. This concise example is synthetic, generated from synthetic inputs:

CostClaw audit
Source: synthetic example (1 session across 1 project)
CLAUDE.md: synthetic input

Cache-miss exposure (estimate): $90.01

Estimated current API-equivalent valuation: $100.01   Cache hit: 0.0%   Session hours (timestamp union): 1.0
Model spend: opus 0.01% / haiku 99.99%

Rule-based setup score: 74 / 100 (Solid)
  CLAUDE.md quality      72
  Context hygiene        50
  Prompting patterns     75
  Session management     100
  Tool and MCP config    88
  Cost discipline        67

Top opportunities by estimated exposure:
  - [$90.01] Reduce cache-miss exposure
      Synthetic cache-read counterfactual; cold and unique inputs may not be cacheable.

The audit applies rules to observed cache and setup patterns. Its suggested causes and actions are hypotheses to inspect, not diagnoses or proof that a change will save money. Burn Clock needs at least 7 active days of logs; below that it is left out.

On a subscription? Declare your plan

Every dollar the audit prints is an API-equivalent price: what those tokens would cost at pay-as-you-go rates. On a Claude subscription (Pro or Max) your usage within an included allowance may have no marginal token charge. Extra Usage can be billed, so API-equivalent figures are neither money back nor a statement of your actual subscription charges.

The first interactive run asks which one you are on and remembers the answer, so usually there is nothing to do. To set it directly, or to change it later:

npx costclaw audit --plan max20x    # or pro, max5x; --plan api switches back

Piped runs, --json and CI are never asked and assume API rates, so a scripted audit never blocks waiting for an answer.

The headline becomes cache-miss exposure - a counterfactual comparison of logged token use with a cache-read scenario - with dollars as API-equivalent context. The following uses the same synthetic example:

Cache-miss exposure (counterfactual): 90.0% of analyzed usage ($90.01 at API rates)

Estimated current API-equivalent valuation: $100.01   Cache hit: 0.0%   Session hours (timestamp union): 1.0
Plan: max20x. This synthetic example does not measure quota, billing, or promise
more work. Activity windows are omitted when there is insufficient history.

Usage windows are fixed activity bins based on local timestamps. They summarize observed activity only: CostClaw does not know Anthropic's actual quota, rate-limit windows, subscription inclusion, or billing adjustments.

The value is saved to ~/.costclaw/config.json, so later runs (and optimize) remember it. The findings and their ranking are identical either way; only the unit is framed to match how you actually pay.

Options

costclaw audit [--path <dir>] [--claude-md <file>] [--plan <plan>] [--json] [--html [file]] [--no-html] [--card [file]]

--path <dir> audit a specific projects directory (default ~/.claude/projects). To audit one project instead of all of them, pass that project's own directory under ~/.claude/projects — the one named after its path, like ~/.claude/projects/C--Users-you-Projects-myapp. The report then covers that project alone and says 1 project.
--claude-md <file> score a specific CLAUDE.md file's quality (by default the audit scores ~/.claude/CLAUDE.md when it exists).
--plan <api|pro|max5x|max20x> declare how you pay for Claude (see above); persisted for later runs.
--json print the raw, derived AuditRecord instead of the human report.
The HTML report is written and opened in your browser by default (costclaw-report.html in the current directory). The file inlines everything, so nothing is fetched and nothing is uploaded; the terminal report still prints (in color on interactive terminals; set NO_COLOR to disable). --html <file> picks the path; --no-html skips the file; --json runs stay file-free unless --html is passed explicitly. Set COSTCLAW_NO_OPEN=1 to write reports without launching a browser (CI and test runners are detected and never open one). The report ends with a "What to do next" ramp: the commands to run next, how the optimize license works, and a command reference.
--card [file] also write a shareable score card SVG (default costclaw-card.svg): your score, band, cache-miss exposure estimate, cache hit rate, and strongest pillar. A static file, no fonts or network calls.

Run costclaw --version (or -v / costclaw version) to print the installed CLI version.

Accuracy boundary

The report estimates current API-equivalent list-price value from logged usage and a dated rate table. It is not billing proof. Unknown model IDs, unavailable pricing modifiers, and incomplete logs add uncertainty. Repeated cumulative request updates are counted once using the highest coherent observed total; logged cache TTL splits are priced when available. A top-level/split conflict retains the valid top-level count at the conservative one-hour rate with a warning; legacy writes without a split use five-minute pricing with a warning. Cache-miss exposure is a counterfactual, and the setup score uses rules rather than a provider quality grade. The release retests these boundaries with npm test --workspace @costclaw/engine -- accuracy-regression and npm test --workspace costclaw -- accuracy-report.

Diff

Every audit run saves a snapshot of the derived record to ~/.costclaw/history (local, nothing uploaded). Run the audit again after you have made changes, then:

npx costclaw diff

That compares your latest two audits and shows movement in the estimates. It does not verify money recovered. The numeric example below is illustrative:

CostClaw diff
Baseline: 2026-06-09    Current: 2026-07-09    (30 days)

Since the baseline:
  New spend              $842.10 across 210 new sessions
  Marginal cache hit     97.1%  (lifetime 96.2%)
  Cache-miss exposure (estimate)   +$96.40 (now $1131.61)

Rule-based setup score: 83 -> 86  (+3, Tight)
  CLAUDE.md quality       69 ->  78   (+9)
  ...

Fixes resolved since the baseline:
  - [$52.40] Review model fit for 61 small sessions

The marginal cache hit rate covers only the period between the two audits, which a lifetime average hides. You can also diff two explicit records saved with costclaw audit --json: costclaw diff baseline.json current.json. Add --json for the machine-readable diff. Free, like the audit. The history keeps the newest 50 snapshots and prunes older ones automatically.

Badge

npx costclaw badge

Runs a fresh audit and writes a shields.io-style badge SVG (default costclaw-badge.svg): a "costclaw" segment and your overall score, colored by its band. Drop it in a README with a plain image tag:

![costclaw score](./costclaw-badge.svg)

costclaw badge [--path <dir>] [--claude-md <file>] [--out <file>]

Optimize

The numeric examples in this section are illustrative placeholders, not output from an account or a promise of savings.

npx costclaw optimize

Generates, for every project your audit saw, five artifacts: an optimized CLAUDE.md scaffold, a prioritized fix playbook, a conservative, project-derived settings.suggested.json permission allowlist, a HARNESS-UPGRADE.md work order for your own Claude Code, and costclaw.md (the generated sections as a standalone include). It never writes inside a project; only costclaw apply does that, and only on an explicit command.

It also reviews the files themselves. The dashboard shows your global ~/.claude/CLAUDE.md, plus every file it imports with an @path line, and each project's CLAUDE.md annotated line by line: what to remove (the generated include now carries it, or the global file already says it), what to move out (dated and status text, a paragraph that names only one project), and what to add (a short, evidence-backed block, never a placeholder). Above that sits one prompt, UPGRADE-ALL.md, covering the global file and every project at once:

claude "Follow ~/.costclaw/optimize/UPGRADE-ALL.md"

It states each file's per-turn token total before and after the proposed changes, and no target line count anywhere. A project with no CLAUDE.md of its own now reports no "before" instead of comparing against your global file, which was never that project's text.

By default it runs globally: it ranks your audited projects by spend, generates for the top ones (cap 10; override with --limit N) into ~/.costclaw/optimize/<project>/, writes UPGRADE-ALL.md and one DASHBOARD.html index at the root listing every project with its receipt and apply line, plus a local click-to-apply page you can use instead of the command line (Ctrl+C, the page's Done button, or --no-serve to skip it). --project <dir> keeps the single-project behavior, writing into ./costclaw-out (or --out <dir>) instead. --no-dashboard skips the HTML.

And it tells you what it actually did to the file that rides on every turn:

Your CLAUDE.md: an estimated 5,266 tokens to 2,479 (52.9% smaller), paid on every turn.

costclaw never calls a model, so it does not rewrite your prose: your own sections are carried through exactly as written. When that carried prose is most of what is left, the receipt says so rather than presenting a small percentage as a win:

About 1,714 of those tokens are your own prose, carried through as written.
costclaw does not rewrite prose, so trimming it is judgment work: HARNESS-UPGRADE.md
ranks your heaviest sections and flags the dated lines to move into docs/.

HARNESS-UPGRADE.md is the fourth artifact: a work order you hand to your own Claude Code (claude "Follow costclaw-out/HARNESS-UPGRADE.md"). It carries the merge and permission tasks plus evidence-conditional ones, and when your carried prose is heavy it ranks it so the trimming is a worklist instead of a guess:

Heaviest carried sections, largest first:

- Core Philosophy: est. 1,382 tokens.
- How to Work: est. 1,267 tokens, 2 dated lines.
- Communication and Output: est. 550 tokens, 3 dated lines.

The remaining 6 carried sections account for the other 1,880 tokens.

Those rows plus the remainder line add up to the stated total, the same way the playbook's per-project table reconciles. costclaw sets no target line count anywhere: it measures what your sections cost and which lines carry dates, and leaves the keep-or-move judgment to you.

The playbook breaks the cache-miss exposure estimate down by project, so you can see which repository has modeled exposure and at what cache hit rate:

### Where that money is

| Project | Cache-miss exposure (estimate) | Cache hit | Main sessions |
| --- | --- | --- | --- |
| some-app | $490.43 | 98% | 229 |
| another-app | $312.43 | 99% | 131 |

39 smaller projects account for the remaining $172.06.

The rows plus that remainder line always add up to the headline figure above them, so the breakdown reconciles rather than approximating.

costclaw optimize [--path <dir>] [--claude-md <file>] [--project <dir>] [--out <dir>] [--limit <n>] [--no-dashboard] [--no-serve] [--force]

Apply

npx costclaw apply

The only command that writes inside a project, and only additively. Run it from inside the project, or pass a directory:

costclaw apply [<dir>] [--remove] [--replace] [--apply-settings [file]] [--from <dir>] [--force]

Default mode writes the generated sections to .claude/costclaw.md and adds one @.claude/costclaw.md import line (Claude Code's memory import syntax) to your CLAUDE.md. Every line you wrote stays exactly as it was. Idempotent: running it again rewrites the include and leaves the import line alone.
--remove undoes it: deletes .claude/costclaw.md and .claude/costclaw/, and strips the import line (only that exact generated line).
--replace is the old wholesale rewrite. It requires a git repository (a .git directory in the project), so the undo is git checkout -- CLAUDE.md; outside git it refuses. It still keeps a .bak as a second net, refusing to overwrite an existing one without --force.
--apply-settings [file] additively merges the derived permission allowlist into your Claude Code settings. Opt-in: it only touches permissions.allow and permissions.deny (a deduped union that keeps your existing entries and orders them first) and never removes or changes any other key. The default target is the project's .claude/settings.json; pass [file] to target another. It backs up the previous file to <target>.bak, prints a diff, then writes pretty JSON. A missing target is created; a file it cannot JSON.parse (for example JSONC with comments) is refused and left untouched.
--from <dir> points at a specific artifacts folder instead of looking one up by project. Without it, apply finds artifacts from the last optimize run, or generates them cold (into ./costclaw-out) if none exist yet.
--force allows overwriting an existing .bak backup for --replace and --apply-settings.

optimize and apply need a one-time license (costclaw activate <key>); audit is free.

Privacy

The audit saves a derived AuditRecord: totals and generated prose, with no raw prompt text, file paths, or secrets. A hosted dashboard is on the roadmap and would receive only that derived record, never your logs.