claudebill

Product Introduction

1. Definition: claudebill is a command-line interface (CLI) tool and cost analytics engine for Anthropic's Claude Code. It is a retroactive, offline log parser that transforms Claude Code's native session transcripts into detailed, actionable cost reports.
2. Core Value Proposition: It exists to provide transparent, granular, and private cost visibility for Claude Code usage. It solves the "black box" problem of AI-assisted development spend by analyzing local log files to show costs per session, project, git branch, and model, enabling developers and teams to optimize AI coding expenses and understand their return on investment.

Main Features

1. Retroactive & Offline Log Analysis: claudebill parses the .jsonl transcript files that Claude Code automatically writes to ~/.claude/projects/. It requires no prior installation or configuration hooks. The analysis is performed entirely offline, ensuring data privacy and security as no session data is transmitted over the network.
2. Granular Cost Breakdown & Filtering: The tool provides multiple report views: summary totals, cost per session, per project directory, per git branch, per AI model (e.g., Claude Opus, Fable), and daily trends. Advanced filters (--since, --until, --project, --branch, --model) allow for precise forensic analysis of spending patterns.
3. Git Branch Merge Analysis: A key innovation is correlating AI spend with git workflow outcomes. The branches --merged command classifies spending into shipped, open, abandoned, or unknown branches. This directly ties cost to productivity, distinguishing valuable investment from waste on dead-end work.
4. Prompt Cache Economics: claudebill explicitly details the impact of Claude's prompt caching feature. It reports cache hit rates, calculates savings from cache reads, and identifies sessions with poor cache performance, helping users validate the feature's ROI.
5. Headless & CI/CD Ready: Designed for automation, it can analyze logs from CI runners or headless environments by pointing to an alternate config directory (--dir or CLAUDE_CONFIG_DIR). Output formats like --json and --csv enable integration with custom dashboards and data warehouses.

Problems Solved

1. Pain Point: Lack of visibility into Claude Code spending. Users receive a monthly subscription bill or usage meter but cannot answer specific questions like "Which refactoring session cost $50?" or "Is our new AI model more cost-effective than the old one?"
2. Target Audience: Software developers, engineering managers, DevOps engineers, and finops professionals who use Claude Code for development and need to track, budget, and justify its operational cost. It's critical for teams scaling AI-assisted development.
3. Use Cases: Auditing a month's spend to identify wasteful patterns; calculating the API-equivalent cost to evaluate a subscription plan's value; attributing AI costs to specific projects or clients for billing; optimizing prompt and model usage based on cost-per-turn data; analyzing CI pipeline costs for AI-generated code.

Unique Advantages

1. Differentiation: Unlike cloud-based SaaS dashboards, claudebill is offline-first and private. It has zero dependencies (pure Node.js) and is retroactive, analyzing all historical data immediately. It uniquely integrates git metadata for cost attribution to engineering outcomes.
2. Key Innovation: Its immutable, versioned pricing model. Every report is stamped with a prices_version date. This prevents historical cost data from being silently altered by future API price changes, ensuring audit integrity. Users can pin to a specific price table using --prices.

Frequently Asked Questions (FAQ)

1. Does claudebill work with old Claude Code sessions? Yes, its core function is retroactive analysis. It reads all existing .jsonl transcript files in the Claude config directory, allowing you to analyze costs from your very first session without any prior setup.
2. How does claudebill calculate costs for Claude Pro or Team subscriptions? It displays the API-equivalent cost (USD) for the tokens consumed. This allows subscribers to compare their flat-rate fee against pay-as-you-go API pricing to determine if their plan is cost-effective, using commands like claudebill summary --plan max20.
3. Is claudebill safe for private code? Does it send my data online? No data is sent online. claudebill operates with complete offline privacy, reading only local log files and your local git history. It does not make network requests or contain telemetry.
4. Can I use claudebill to analyze costs from CI/CD pipelines or remote servers? Yes. By setting the CLAUDE_CONFIG_DIR environment variable or using the --dir flag, you can point claudebill at the transcript directory on any machine (e.g., a GitHub Actions runner) and export data via --json or --csv for centralized reporting.
5. How does claudebill handle custom or local LLM models not in Anthropic's price list? Unknown model IDs are tracked in token counts but listed as "unpriced." You can define custom rates (including zero rates for local models) by creating a JSON pricing file and passing it with the --prices flag for complete cost coverage.