# claude-code-cost - See your Claude Code spend per project, branch, and over time

> A Claude Code plugin. `/claude-code-cost:report` shows your Claude Code spend in USD, per project and per git branch, computed locally by reading the JSONL session logs Claude Code already writes under `~/.claude/projects/`. The `by-day`, `by-week`, `by-month`, and `by-project` commands break the same data down over time. Each response is priced point-in-time from a bundled copy of the open ai-price-index dataset, so there is no runtime network.

**Trust pledge:** Zero key. Zero prompts. Zero latency. claude-code-cost never touches API traffic. It is not a proxy. It only parses what Claude Code already writes to local disk.

- HTML page: https://roninforge.org/claude-code-cost
- Source: https://github.com/RoninForge/claude-code-cost
- Latest release: see https://github.com/RoninForge/claude-code-cost/releases
- License: MIT for the tooling; the bundled pricing data is CC BY 4.0

## Install

claude-code-cost installs through the Claude Code plugin system. There is no binary to download, no curl pipe, and no Homebrew step. Inside Claude Code, run:

    /plugin marketplace add RoninForge/claude-code-cost
    /plugin install claude-code-cost@roninforge

Then run:

    /claude-code-cost:report

It requires `node` (>= 18) on your PATH, which Claude Code users almost always have.

## Commands

Every command is namespaced under `/claude-code-cost` (Claude Code namespaces all plugin commands; the bare `/cost` is Claude Code's own built-in session-cost view, not this plugin). Each takes an optional case-insensitive substring `[filter]` on the project or branch name, plus `--json`.

    /claude-code-cost:report       spend per project + branch (today / week / month)
    /claude-code-cost:by-day       spend per day, dated, most recent first (~30 days)
    /claude-code-cost:by-week      spend per Monday-based week, dated (~12 weeks)
    /claude-code-cost:by-month     spend per calendar month, dated (~12 months)
    /claude-code-cost:by-project   per project (branches merged) + last active date

### report

`/claude-code-cost:report` prints your Claude Code spend in USD, grouped by project and by the git branch that was checked out when each response ran, for three periods: today, the current Monday-based week, and the current calendar month (all in UTC).

    > /claude-code-cost:report

    PROJECT     BRANCH        TODAY    WEEK     MONTH
    myapp       main          $4.85    $28.30   $112.40
    myapp       feature/auth  $1.20    $3.20    $3.20
    side-proj   main          $0.00    $0.50    $14.10
    TOTAL                     $6.05    $32.00   $129.70

### by-day / by-week / by-month

The dated views answer "when did I spend?". Each row is a date bucket, most recent first, with a TOTAL footer. Only buckets with spend appear. Add a filter to scope a single project or branch.

    > /claude-code-cost:by-day

    DATE        SPEND
    2026-06-23  $9.98
    2026-06-22  $4.20
    2026-06-19  $7.49
    TOTAL       $21.67

### by-project

`/claude-code-cost:by-project` collapses every branch into one row per project, ranked by month spend, and adds a `LAST` column with the most recent day that project had any spend.

    > /claude-code-cost:by-project

    PROJECT     TODAY    WEEK     MONTH    LAST
    myapp       $6.05    $31.50   $115.60  2026-06-23
    side-proj   $0.00    $0.50    $14.10   2026-06-19
    TOTAL       $6.05    $32.00   $129.70

## How it computes cost

1. Reads `~/.claude/projects/**/*.jsonl`, the session logs Claude Code already writes to disk.
2. Counts each billable assistant response once. Claude Code writes the same response across several JSONL lines, so the repeated lines are deduped before pricing.
3. Attributes each response to its project (the working-directory name) and the git branch recorded on the line.
4. Prices each response point-in-time from a bundled copy of the open ai-price-index dataset, at the rate that was in effect on that response's own date. Input, output, cache-read, and cache-write tokens are all counted. A later price change never rewrites past spend.
5. Surfaces unknown models in the output rather than silently dropping them, so a new Anthropic model never makes your spend look artificially low.

## What it does NOT do

- Does not read prompts or responses. It uses only the token counts, model, working directory, git branch, and timestamp on each JSONL line.
- Does not see your API key. It never opens a connection to Anthropic.
- Does not proxy, intercept, or modify requests. It is a local log reader.
- Does not upload anything. Nothing leaves the machine.

## Compatibility

- API-billed usage: exact dollar costs from token counts and point-in-time per-token pricing.
- Subscription plans (Pro, Max): token consumption tracked and priced as a usage metric, so you can see which projects and branches burn the most of your plan even though billing is flat-rate.

## Optional BudgetClaw integration

claude-code-cost is fully self-contained. If BudgetClaw (https://roninforge.org/budgetclaw) is also installed, `/claude-code-cost:report` uses it automatically for a richer view backed by a persistent database and budget caps. If BudgetClaw is not present, the built-in reader is used. Run `/claude-code-cost:report --self` to force the built-in reader either way. The dated views (`by-day`, `by-week`, `by-month`, `by-project`) always read the raw logs directly, because `budgetclaw status` only emits the pre-rolled today/week/month snapshot with no per-date data.

For spend across providers and machines in one place, the Goei dashboard (https://goei.roninforge.org) is an opt-in next step, not a requirement.