Kerf-CLI: The SQLite-Powered Cost Dashboard Every Claude Code User Needs

What Kerf-CLI Does — SQLite-Powered Claude Code Cost Intelligence

Kerf-CLI (named after the "kerf" or material removed by a cutting tool) is a 100% local, SQLite-backed analytics tool that reads your Claude Code session data and surfaces exactly where your money is going. It tracks wasted Opus spend, calculates cache hit rates, enforces budgets via Claude Code hooks, and provides a polished local web dashboard—all without sending any data to the cloud.

The core insight: every Claude Code user is flying blind about costs. You might know your monthly bill, but not which sessions or which model choices are driving it. Kerf solves this by ingesting your Claude Code session JSONL files into a local SQLite database you can query directly.

Setup — 5 Commands to Full Visibility

Installation is straightforward:

npm install -g kerf-cli
# or use without installing:
npx kerf-cli@latest <command>

Then run the essential workflow:

kerf init          # One-time setup (creates DB, installs hooks)
kerf sync          # Import Claude Code sessions into SQLite
kerf dashboard     # Open the polished web UI at http://localhost:3847

The kerf init command offers several modes:

• kerf init (default): Install warning-mode hooks (safe)
• kerf init --enforce-budgets: Install PreToolUse hook that BLOCKS usage when over budget
• kerf init --global: Install hooks in ~/.claude/ (applies to all projects)
• kerf init --no-hooks: Just create database, skip hooks

The Dashboard — What You'll Actually See

Open kerf dashboard and you get:

Hero Metrics: Cost, sessions, tokens, cache hit rate with trend arrows vs prior period
Budget Card: Progress bar, remaining amount, reset timer
Efficiency Card: Potential monthly savings if Opus traffic were routed to Sonnet
Cache Card: Hit rate donut chart, money saved from cache
Cost Chart: Stacked area chart broken down by Opus/Sonnet/Haiku usage
Session Table: Click any row to expand full details
Period Picker: Today/week/month/all time
Live Indicator: Auto-refreshes every 5 seconds

All queries run directly against SQLite, so the dashboard loads in <100ms even with thousands of sessions.

Key Commands for Daily Claude Code Work

Beyond the dashboard, these commands give you quick insights:

# What did I spend today?
kerf summary

# Last 7 days
kerf summary --period week

# Am I wasting money on Opus?
kerf efficiency

# Machine-readable sync stats
kerf sync --json

# Diagnose your setup
kerf doctor

The kerf doctor command is particularly useful—it checks 10 things and tells you how to fix each one, like whether you have budgets configured or if your database schema is up to date.

Why This Matters for Claude Code Users

Most developers using Claude Code have no visibility into:

1. Cache efficiency: What percentage of requests are hitting cache vs. costing real money?
2. Model optimization: How much could you save by routing appropriate tasks to Sonnet instead of Opus?
3. Budget enforcement: How to automatically block usage when you hit a spending limit?
4. Session-level analysis: Which specific coding sessions are driving your costs?

Kerf answers all these questions with a local-first approach that respects your privacy. No API keys, no telemetry, no cloud dependencies.

The SQLite Advantage

Because Kerf uses SQLite as its backend, you can query your own data directly:

-- Find your most expensive sessions
SELECT session_id, total_cost_usd, model
FROM sessions
ORDER BY total_cost_usd DESC
LIMIT 10;

-- Calculate daily spending trends
SELECT date(created_at) as day, SUM(total_cost_usd) as daily_cost
FROM sessions
GROUP BY day
ORDER BY day DESC;

This open data approach means you're never locked into Kerf's visualization—you can build your own reports, connect to BI tools, or analyze patterns that matter specifically to your workflow.

When to Use Kerf-CLI

Immediately if:

• Your Claude Code monthly spend exceeds $50
• You work on multiple projects and want per-project cost tracking
• You suspect you're overusing Opus for tasks Sonnet could handle
• You need to justify Claude Code usage to your team or company

Consider waiting if:

• You're just experimenting with Claude Code (costs under $10/month)
• You exclusively use the free tier
• You already have comprehensive cost monitoring through Anthropic's dashboard

Limitations to Know

Kerf reads Claude Code's session files, so it can only analyze what Claude Code logs. If you use Claude through other interfaces (web, API directly), those costs won't appear here. The tool also requires Node.js and assumes you're comfortable with CLI tools.

The Bottom Line

Kerf-CLI fills a critical gap in the Claude Code ecosystem: cost transparency. For developers serious about using Claude Code professionally, understanding and optimizing spend isn't optional—it's essential. Kerf gives you that visibility with a polished, local-first tool that respects your data privacy while providing actionable insights.

Install it today, run kerf sync, and within minutes you'll know exactly where your Claude Code budget is going—and how to optimize it.