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

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
      Keep the start of each session stable so the prompt cache is reused.
      Evidence: XX% of input tokens missed the cache across N sessions.

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.
• --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

Turns the same audit into done-for-you artifacts: an optimized CLAUDE.md scaffold, a prioritized fix playbook, and a conservative, project-derived settings.suggested.json permission allowlist. It scans --project <dir> (default: the current directory) to auto-fill the scaffold from your real files. By default it dry-runs into ./costclaw-out and touches none of your files.

costclaw optimize [--path <dir>] [--claude-md <file>] [--project <dir>] [--out <dir>] [--write <file>] [--apply-settings [file]] [--force]

• --write <file> applies the optimized CLAUDE.md in place, after backing up the original to <file>.bak and printing a diff.
• --apply-settings [file] merges the derived permission allowlist into your Claude Code settings. Opt-in and additive: 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 scanned 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.
• --force allows overwriting an existing .bak backup for --write and --apply-settings.

optimize needs 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.