RoninForge / Tutorials / Track Claude Code spend over time

~1.6k tokens | View as Markdown |

Tutorial

How to track your Claude Code spend over time, per project and branch

The built-in /cost shows one session and forgets it the moment you start the next. This tutorial installs the claude-code-cost plugin so you can see spend per project, per git branch, and broken down by day, week, and month. No binary, no account, no keys. It reads the logs Claude Code already writes to disk.

Problem

No history of where spend went

Time

2 minutes

Output

Spend by project, branch, and date

The problem

You run Claude Code across a dozen projects and branches in a week, and at the end of it you have no idea where the money went. The built-in /cost answers only one question: what does this conversation cost right now. It cannot tell you which project ate the most this month, or whether yesterday was an expensive day, or how a feature branch compares to main.

claude-code-cost answers the questions /cost cannot:

  • Where did it go? Spend grouped by project and the git branch that was checked out when each response ran.
  • When did it happen? Dated breakdowns by day, week, and month, most recent first.
  • Is it accurate over time? Each response is priced at the rate that was live on its own date, so a later price change never rewrites history.

Everything below runs inside Claude Code. There is no binary to download, no curl pipe, and no Homebrew step. The plugin needs only node (>= 18) on your PATH, which Claude Code users almost always have.

Step 1

Add the marketplace and install the plugin

Inside any Claude Code session, add the RoninForge marketplace:

Then install the plugin from it:

That is the whole install. The plugin is git-cloned, not downloaded as a binary, and its pricing data is bundled inside it. There is nothing to log in to and no key to paste.

Step 2

See spend per project and branch

Run the report. It groups your spend by project and by the git branch checked out when each response ran, for today, the current week, and the current month:

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

Note the command form: /claude-code-cost:report, not /cost. Claude Code namespaces every plugin command as /<plugin>:<command>, and bare /cost is reserved for the built-in session view.

Step 3

See when you spent

The dated views answer "when did the money go out?". Each row is a date bucket, most recent first, with a TOTAL footer. Only buckets with spend appear.

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

The same shape is available at two coarser grains:

  • /claude-code-cost:by-week - one row per Monday-based week, about the last 12 weeks.
  • /claude-code-cost:by-month - one row per calendar month, about the last 12 months.

All dates are bucketed in UTC, the same convention Claude Code uses in its own logs.

Step 4

Roll up per project

When branches are noise and you only care about projects, collapse every branch into one row each. :by-project ranks projects by month spend and adds a LAST column with the most recent day that project had any spend:

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

The LAST column makes it obvious which projects are still active and which have gone quiet but still booked spend earlier in the month.

Step 5

Filter to one project, or export JSON

Every command takes an optional first argument: a case-insensitive substring of a project or branch name. It scopes the whole view, so the dated commands double as a single-project history:

Add --json to any command and it prints a JSON array instead of the table, ready to pipe into a script or a spreadsheet:

One more flag, on :report only: --self forces the built-in reader even if BudgetClaw is installed. More on that integration below.

How it computes the numbers

  1. 1 Read. A single pass over ~/.claude/projects/**/*.jsonl, the session logs Claude Code already writes to disk.
  2. 2 Dedup. Claude Code writes the same response across several JSONL lines. Each billable response is counted once before pricing.
  3. 3 Price. Each response is priced at its own date from the bundled open ai-price-index dataset (CC BY 4.0), counting input, output, cache-read, and cache-write tokens. Unknown models are surfaced in a footer note rather than silently dropped.
  4. 4 Aggregate. That one priced-event list feeds every view: per project and branch for :report, per date for the by-* commands.

Optional next steps

Add a hard spend cap with BudgetClaw

claude-code-cost is read-only: it tells you what you spent, it does not stop you spending. If you want a daily ceiling that ends a session on breach, install BudgetClaw and follow the spend-cap tutorial. When BudgetClaw is present, /claude-code-cost:report automatically reads from it for a richer view.

Unify providers in one dashboard

To see Claude Code spend next to other AI providers across machines, Goei at goei.roninforge.org rolls it up into one view. The plugin stays a local, read-only tool; the dashboard is an opt-in step, not a requirement.

Trust pledge

claude-code-cost never sits between your editor and the Anthropic API. It reads only the JSONL files Claude Code already writes to local disk, and it uses just the token counts, model, project, branch, and timestamp on each line. Prompt and response text are ignored. The pricing data is bundled at build time, so there is no network call. No API keys held, no prompts captured, no latency added. Zero key, zero prompts, zero latency.

FAQ

Why is the command /claude-code-cost:report and not just /cost?

Claude Code namespaces every plugin command as /<plugin-name>:<command>, so a plugin can never own a bare command name. Bare /cost is already a built-in Claude Code alias for the current session's usage view. That is why this plugin's commands read /claude-code-cost:report, :by-day, :by-week, :by-month, and :by-project.

How is this different from the built-in /cost?

The built-in /cost reports the current session only and resets when you start a fresh one. claude-code-cost aggregates every session on disk, attributes each response to its project and git branch, and breaks the totals down by day, week, month, and project. /cost is per-conversation; claude-code-cost is per-attribution and historical.

Do I need BudgetClaw installed?

No. claude-code-cost is self-contained and ships its own JSONL reader and bundled pricing data. If BudgetClaw happens to be installed, /claude-code-cost:report uses it automatically for a richer view backed by its database. Pass --self to force the built-in reader. The dated views always read the raw logs directly.

Are old responses repriced when Anthropic changes prices?

No. Each response is priced at the rate that was in effect on its own date, using the bundled open ai-price-index dataset. A later price change never rewrites your past spend, so historical numbers stay stable.

Does it work on Claude Pro or Max subscriptions?

Yes. It reads the same local JSONL logs regardless of how you are billed. On API usage the dollar figures are your real cost. On flat-rate Pro and Max plans, token usage is still tracked and priced as a metric so you can see which projects and branches burn the most of your plan.

What does the plugin read, and does anything leave my machine?

It reads only the local JSONL session logs under ~/.claude/projects/, using the token counts, model id, working directory, git branch, and timestamp on each line. Prompt and response text are ignored. There is no network call: the pricing data is bundled at build time, so nothing is uploaded and nothing leaves your machine.

Source