Claude Code's cost transparency problem is so severe that a developer spent weeks building an open-source tool just to answer basic questions about where their money goes. Dhanushkumarsivaji logged into Claude Code, saw Anthropic's reassuring message that Max subscribers "don't need to monitor cost," then discovered he'd burned through 91% of his weekly token limit in a single morning without knowing which project or model consumed it .

Why Claude Code's Built-In Cost Tracking Falls Short?

Anthropic provides developers with granular billing data, but the tools to understand it are nearly nonexistent. The Claude Code /cost command only shows current session spending and actively discourages Max subscribers from investigating further. Anthropic's web console offers organization-level dashboards exclusively for Teams and Enterprise customers, leaving solo developers on Pro and Max plans with almost no visibility .

Existing third-party solutions like ccusage provide quick reports but lack persistence, forcing users to parse raw data files on every query. This gap between available data and usable analytics created the perfect problem for a developer frustrated by surprise bills.

What Kerf-CLI Actually Does?

Kerf is a TypeScript command-line tool that transforms Claude Code's session logs into a queryable local database. Instead of staring at raw JSON files, developers can now ask specific questions: "Which projects are eating Opus tokens unnecessarily?" and "What's my actual cache hit rate over the last 30 days?" . The tool reads Claude Code's existing session files stored in the user's home directory, ingests them into a local SQLite database, and makes everything searchable through SQL queries or a web dashboard running on localhost.

The architecture prioritizes speed and privacy. After an initial sync that ingests every Claude Code session ever created, subsequent updates are incremental, only re-parsing changed files. All queries run against the local database, meaning no data leaves the developer's machine.

How to Optimize Your Claude Code Spending

• Switch Opus to Sonnet for routine tasks: Analysis of a month of kerf data revealed 90% of Opus tokens were used on sessions with no complexity signals like debugging or architecture decisions, just file edits and small fixes. Switching these workflows to Sonnet achieved a 4x cost reduction with zero measurable quality difference .
• Monitor cache hit rates aggressively: Cache reads can represent 60 to 80% of total costs. While cache reads are billed at only 10% of standard input rates, developers often cache 50,000 tokens per turn and read them repeatedly, making cache optimization the single largest cost lever available .
• Set hard budget caps with enforcement: Kerf's budget feature blocks Claude Code from executing tool calls once spending exceeds a weekly cap, using Claude Code's native hook system to enforce limits before actions run, not just warn after the fact .
• Understand the 5-hour billing window: Max subscribers are billed against a rolling 5-hour window, not a daily quota. Without tracking this, developers can face surprise charges when the window rolls over mid-session .

The Specific Numbers Behind the Cost Crisis

A typical week of Claude Code usage tells the story. One developer's kerf summary showed a weekly cost of $178.04 across 25 sessions consuming 454 million tokens, with a 98% cache hit rate. The breakdown revealed projects consumed $117 (66% of costs), subagents $42.50 (24%), and kerf itself just $14.54 (8%) . These numbers expose how easily costs spiral when developers default to the most powerful model without understanding which tasks actually need it.

The efficiency analyzer proved transformative. After identifying that most Opus sessions had patterns suitable for Sonnet, switching those workflows cut a meaningful chunk of the monthly Claude bill with zero quality degradation. This single optimization paid for the tool's development time within days.

Why Local-First Design Matters for Developer Trust

Kerf deliberately avoids cloud synchronization, authentication systems, and data storage. The developer explained that adding cloud features would require privacy controls, GDPR compliance, and a business model, none of which serve the primary use case of understanding spending patterns . The local-only approach means developers maintain complete control over their billing data while getting sub-100-millisecond query responses from SQLite.

The tool's roadmap includes support for Cursor and Codex, Slack and Discord budget alerts, and GitHub Actions integration for cost gates on pull requests. A paid team tier for cloud sync and organization-wide aggregation is planned for version 3.x, but the core CLI will remain free and MIT licensed .

Kerf-cli represents a broader pattern in the AI developer ecosystem: when commercial tools lack transparency, developers build their own. The fact that someone spent weeks reverse-engineering Claude Code's billing system to answer basic cost questions suggests Anthropic has an opportunity to embed these analytics directly into the product, turning a frustration point into a competitive advantage.