costclaw

costclaw

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 fixes by the dollars they recover.

Your prompts never leave your machine. The audit parses the logs already on your disk and prints a report. It uploads nothing.

Use it

Requires Node 20+.

npx costclaw audit

That reads ~/.claude/projects (override with --path <dir>) and prints:

CostClaw audit
Source: ~/.claude/projects (N sessions across M projects)
CLAUDE.md: ~/.claude/CLAUDE.md

Recoverable spend (cache-miss exposure): $XXX.XX

Spend analyzed: $X,XXX.XX   Cache hit: 96.3%   Active hours: XXX.X
Model spend: opus 71% / sonnet 24% / haiku 5%

Top projects by spend:
  C--Projects-demo                 $XXX.XX    312 sessions   cache 96.4%   opus

Burn Clock (spend by day):
  Monday     [###########.........]  $XXX.XX
  ...
  Friday     [####################]  $X,XXX.XX

Friday is your most expensive day ($X,XXX.XX), about 2.0x an average day across
42 active days. Peak stretch: Friday morning.

Overall setup score: 91 / 100 (Dialed in)
  CLAUDE.md quality      [#################...] 85
  Context hygiene        [###################.] 95
  Prompting patterns     [##################..] 92
  Session management     [####################] 100
  Tool and MCP config    [####################] 100
  Cost discipline        [##############......] 70

Top fixes by recoverable spend:
  - [$XXX.XX] Recover spend lost to cache misses
      Your longest sessions started at 71% cache reuse and finished at 9%.
      Compact or start a fresh session before the context outgrows the cache.
      Evidence: XX% of input tokens missed the cache across N sessions.

The cache fix names the specific reason your cache is missing, picked from what your logs actually show: sessions whose cache decayed as they ran, a CLAUDE.md churning with dates and TODOs, or a project that keeps starting cold. Burn Clock needs at least 7 active days of logs; below that it is left out rather than guessed at.

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 marginal token cost is zero, so those dollars are not money back - they measure your rate-limit headroom. Declare your plan once and the audit reframes itself honestly:

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

The headline becomes recoverable usage - the share of your token consumption you could win back - with the dollars demoted to API-equivalent context:

Recoverable usage (cache-miss exposure): 14.3% of analyzed usage ($1134.61 at API rates)

Usage analyzed (API-equivalent): $7921.99   Cache hit: 96.2%   Active hours: 1889.7
Plan: max20x. Dollar figures are API-equivalent token value, not money back;
recovering them buys rate-limit headroom (more work per usage window).
Usage windows (5h, like your rate limit): median $8.10, busiest $34.20; busiest week $310.55 (API-equivalent)
Recovering 14.3% buys about 17% more work per window: up to ~42 extra minutes in a window like your busiest.

The usage windows are modeled from your own activity timestamps, mirroring how the limits actually work: a 5-hour window opens at your first activity, and a weekly cap sits above it. Nothing is assumed about Anthropic's actual budgets; everything is relative to your observed consumption ("busiest" is the 90th percentile window, so one freak outlier does not set the bar).

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).
• --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, recoverable spend, 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.

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 the movement, so you can verify the fixes actually recovered dollars:

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%)
  Recoverable exposure   +$96.40 (now $1131.61)

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

Fixes resolved since the baseline:
  - [$52.40] Use a cheaper model 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

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.

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>/, and writes one DASHBOARD.html index 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 recoverable headline down by project, so you can see which repo owes which dollars and at what cache hit rate:

### Where that money is

| Project | Recoverable | 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 only thing the tool produces is a derived AuditRecord: totals and generated prose, no prompt text, no file paths, no secrets. A hosted dashboard is on the roadmap and would receive only that derived record, never your logs.