Local audit for Claude Code
CostClaw reads the Claude Code logs already on your disk, estimates token value from current list prices, and scores your setup across six rule-based pillars. It analyzes prompts locally and never uploads them.
npx costclaw audit No account, no upload. It parses the logs on your disk and prints a report.
~/.claude/projects 1 session · 1 project · CLAUDE.md found
Model spend opus 0.01% / haiku 99.99%
Top opportunity by estimated exposure
The leak
CostClaw reads session logs on your disk, including subagent and workflow sub-logs, and compares logged token use with scenarios worth investigating. It does not reconcile an invoice or guarantee savings. Four signals it shows:
Claude Code caches the front of your prompt so repeat tokens cost a tenth of the price. When a session rebuilds that cache instead of reusing it, you pay full input rate on tokens that should have been lower-priced. CostClaw estimates that counterfactual gap from logged fields.
A session that fires the same tool a hundred times is usually thrashing: re-reading, re-grepping, circling a problem. It does not show up as a line item, but it burns tokens and time. CostClaw counts the loops and flags the sessions that run hot.
A short, simple session does not need the top model. When a quick task runs on Opus that might have been suitable for a cheaper model, CostClaw flags it for review. It does not determine task quality or guarantee a cheaper model would succeed.
A session that runs for hours keeps adding context until the cache stops paying off. The early turns hit it; the closing turns re-pay full price for a prompt that only grew. CostClaw tracks the per-turn cache and flags sessions that may benefit from compaction.
How it works
It reads the JSONL session logs under your Claude directory, including the subagent and workflow sub-logs, in memory, on your machine. Nothing is sent anywhere.
It analyzes raw logs locally to derive dated list-price estimates by reported model, cache hit rate per turn, tool use, and session timing. Prompts, paths, and code are dropped from the output.
It applies rules to six setup pillars and ranks counterfactual opportunities. The report prints to your terminal; estimates are not invoice totals or guaranteed savings.
Stays here. Always.
Optional, on the Pro plan. It only ever receives the derived record above. The free CLI sends nothing at all.
Method. For each accepted logged request, CostClaw applies the dated API list price for its reported model and sums input, output, cache-write, and cache-read token fields. A synthetic 1,000,000-token one-hour Sonnet cache write is valued at $6.00. Repeated cumulative updates are deduplicated so the latest observed total is counted once.
Scope. The report can use logged cache TTL splits when present. If a valid top-level cache-write count conflicts with a nested split, it preserves that count, estimates it at the conservative one-hour rate, and warns. Legacy writes with no split use the five-minute rate with a warning. It cannot establish model provenance, provider discounts, every billing modifier, subscription inclusion, or an Anthropic invoice total.
Interpretation. Cache-miss exposure compares logged usage with a cache-read counterfactual. In a synthetic mixed-model case, the list-price estimate is $0.10001 and the exposure is $0.090009. That is a scenario to investigate, not recoverable money or a quota guarantee. Setup scores are rule-based signals, not provider grades.
What you get
Estimated API-equivalent value over the window you audit, your cache hit rate, and a cache-miss counterfactual. It is based on logged fields and current list prices, not an invoice or a promise of savings.
CLAUDE.md quality, context hygiene, prompting, session management, tooling, and cost discipline. Scores are rule-based signals from the logs, settings, and CLAUDE.md available to the audit. A pillar with no evidence reads n/a; it is not a provider quality grade.
The list leads with the largest modeled scenario and its evidence, then suggests a change to review. Dollar figures are counterfactual estimates, not money promised back.
Burn Clock buckets every dollar by local day and time of day, so you can see the rhythm the bill hides. The peak day is compared against an average day, never against your quietest hour, so the multiplier stays a number you can check against the bars. Under seven active days it reads n/a instead of guessing a pattern.
Synthetic example only: one day with $100.01 in estimated API-equivalent value. Real reports omit a pattern when there is insufficient activity.
Privacy as the moat
The audit saves a derived AuditRecord with totals and generated sentences. Raw prompt text and path markers are covered by privacy tests that run in the build.
The test plants tripwire strings, a fake prompt and a fake client path, into sample logs, runs the full pipeline, and asserts that none of them appear in the record. The build fails if any tested private marker survives.
// the privacy invariant, enforced on every run
const raw = sessionWith({
prompt: "TRIPWIRE_secret_prompt",
path: "/Users/me/clients/acme",
});
const record = buildAudit(analyze(raw));
const json = JSON.stringify(record);
expect(json).not.toContain("TRIPWIRE_secret_prompt");
expect(json).not.toContain("/Users/me/clients/acme");
expect(hasEmDash(json)).toBe(false);Pricing
The CLI is real and usable right now, at no cost. The hosted plan is in progress, and it will only ever see the derived record, never your logs.
$0runs on your machine
npx costclaw audit
One-time license that unlocks costclaw optimize.
It scans your project and writes five artifacts: a filled-in
CLAUDE.md, a ranked fix playbook, suggested settings, a work
order your own Claude Code can apply, and a dashboard that
opens in your browser with the token receipt, the fixes, and
your CLAUDE.md before and after. Verified offline. Your key is
emailed to you in about a minute.
In progress
Want it when it ships? Leave your email.
Not ready yet. The CLI does the core job today.
The audit reads what is already on your disk and prints the report. If it finds nothing, you have lost a minute. If it finds signals, you have a local estimate to investigate.
npx costclaw audit Reads local logs. Sends nothing. No account.