# How to track your Claude Code spend over time, per project and branch > 2-minute setup. The built-in `/cost` shows one session and forgets it. This tutorial installs the claude-code-cost plugin so you can see Claude Code spend per project, per git branch, and broken down by day, week, and month. No binary, no account, no keys. It reads the JSONL logs Claude Code already writes to disk and prices each response point-in-time. Zero key, zero prompts, zero latency. - HTML version: https://roninforge.org/tutorials/how-to-track-claude-code-spend-over-time - Tool used: claude-code-cost - https://roninforge.org/claude-code-cost.md - Audience: developers using Claude Code daily across multiple projects and branches - Last updated: 2026-06-24 against claude-code-cost v1.1.0 ## Why this matters 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, whether yesterday was an expensive day, or how a feature branch compares to `main`. claude-code-cost answers the questions `/cost` cannot: 1. **Where did it go?** Spend grouped by project and the git branch checked out when each response ran. 2. **When did it happen?** Dated breakdowns by day, week, and month, most recent first. 3. **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: /plugin marketplace add RoninForge/claude-code-cost /plugin install claude-code-cost@roninforge 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: > /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 Note the command form: `/claude-code-cost:report`, not `/cost`. Claude Code namespaces every plugin command as `/:`, 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. > /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 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: > /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 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: /claude-code-cost:by-day myapp Add `--json` to any command and it prints a JSON array instead of the table, ready to pipe into a script or a spreadsheet: /claude-code-cost:by-month --json One more flag, on `:report` only: `--self` forces the built-in reader even if BudgetClaw is installed. ## The five commands /claude-code-cost:report spend per project + branch (today / week / month) [filter] [--self] [--json] /claude-code-cost:by-day spend per day, dated, most recent first (~30 days) [filter] [--json] /claude-code-cost:by-week spend per Monday-based week, dated (~12 weeks) [filter] [--json] /claude-code-cost:by-month spend per calendar month, dated (~12 months) [filter] [--json] /claude-code-cost:by-project per project (branches merged) + last active date [filter] [--json] ## How it computes the numbers 1. **Read.** A single pass over `~/.claude/projects/**/*.jsonl`, the session logs Claude Code already writes to disk. 2. **Dedup.** Claude Code writes the same response across several JSONL lines. Each billable response is counted once before pricing. 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. **Aggregate.** That one priced-event list feeds every view: per project and branch for `:report`, per date for the `by-*` commands. ## Optional next steps - **Hard spend cap.** claude-code-cost is read-only: it tells you what you spent, it does not stop you spending. For a daily ceiling that ends a session on breach, install BudgetClaw (https://roninforge.org/budgetclaw) and follow the spend-cap tutorial (https://roninforge.org/tutorials/how-to-set-a-hard-spend-cap-on-claude-code). When BudgetClaw is present, `/claude-code-cost:report` automatically reads from it for a richer view. - **Unified dashboard.** To see Claude Code spend next to other AI providers across machines, Goei (https://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, using 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. ## FAQ **Why is the command `/claude-code-cost:report` and not just `/cost`?** Claude Code namespaces every plugin command as `/:`, 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. **How is this different from the built-in `/cost`?** The built-in `/cost` reports the current session only and resets on 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. Per-conversation versus per-attribution and historical. **Do I need BudgetClaw installed?** No. claude-code-cost is self-contained. If BudgetClaw is installed, `/claude-code-cost:report` uses it automatically for a richer view; otherwise the bundled reader is used. Pass `--self` to force the built-in reader. The dated views always read the raw logs directly. **Are old responses repriced when prices change?** No. Each response is priced at the rate in effect on its own date. A later price change never rewrites past spend. **Does it work on Claude Pro or Max?** Yes. It reads the same local logs regardless of billing. On API usage the dollars are your real cost; on Pro and Max, token usage is tracked and priced as a metric. ## Source - claude-code-cost: https://github.com/RoninForge/claude-code-cost - Product page: https://roninforge.org/claude-code-cost - ai-price-index (bundled pricing data, CC BY 4.0): https://github.com/RoninForge/ai-price-index - This tutorial: https://roninforge.org/tutorials/how-to-track-claude-code-spend-over-time