✦ Costellia

See what every AI query costs you. Costellia reads your Claude Code session logs and renders your spending as a night sky: every query is a star, sized and colored by what it cost. Then it tells you where the money is going and what to do about it.

npx costellia

No install, no account, no API key. Your logs never leave your machine.

Needs Node 20 or newer. Works wherever Claude Code writes its logs — macOS, Linux, WSL.

Running it

npx costellia downloads the package into npm's cache and runs it straight away; it does not put a costellia on your PATH, so plain costellia will say command not found. To look again, run npx costellia again — the second run is instant because the download is cached.

Press Ctrl-C in the terminal to stop the server. Closing the browser tab leaves it running.

If you would rather have the short command, install it properly:

npm install -g costellia   # then just: costellia

Removing it

Costellia reads your logs and writes nothing, so there is no data or config to clean up.

npm uninstall -g costellia          # only if you installed it globally
npm cache clean --force             # clears npm's cache, including the npx copy

npx copies live under ~/.npm/_npx, and npm prunes them on its own — the cache clean is only worth running if you want the disk space back today.

What it shows

• The sky — every query as a star, sized and coloured by cost, clustered by session and project.
• Same tokens, other models — re-prices a query, or the whole range, at Opus / Sonnet / Haiku / Fable rates. Token counts are held fixed, so read it as a direction rather than a quote.
• What tools dragged in — how many characters Read, Bash, WebFetch and friends returned, priced at base input rates. Tool output never appears in a prompt but every character of it becomes context.
• Spend per commit — commits from each project's own repo in the same window as the spend. Correlation, not attribution.
• Session timeline — where a query sits inside its session and what had been spent by that point.
• Search that understands money — >1 for queries over a dollar, <0.05 fix for cheap ones mentioning fix.
• Export — one CSV row per query, for anyone who bills the work on.

Pricing accuracy

Rates come from the published table and are checked in src/server/model-costs.ts: Sonnet 5 bills at $2/$10 (the launch price became permanent), while Opus 4.1 and Opus 4 stayed at $15/$75 — matching them against claude-opus-4-5 would understate those sessions threefold. Turns that ran in fast mode are billed at the premium rate the usage.speed field reports, not at the model's standard row, so a /fast session is not read at half its real cost. A model with no price on file is shown in grey, tokens only; it is never guessed.

Free and paid

This CLI is free and complete — /api/license reports Pro, so nothing here is gated. Every card, the model re-pricing, the session timelines and the CSV export all run without a key.

The paid product is the Mac app: a native menu bar that carries today's spend, the live prompt flow and daily budget alerts — those are free there too — plus a licensed tier that unlocks the same six analyses this CLI already gives you: model re-pricing, tool weight, spend per commit, session timelines, per-project daily trend and CSV export. Licenses are Ed25519 keys verified offline: no activation server, nothing sent anywhere.

What you get

The sky. Projects are hubs, sessions branch off them, and every query is a star. Big and red means expensive; small and blue means cheap. One glance tells you which project — and which prompt — is burning the budget.

The detail panel. Click any star: the full prompt, the model, a token breakdown (input / output / cache write / cache read), the dollar figure, and a plain-language line explaining why it cost that much — "82% of this was cache writes: long context uploaded and stored."

The insights drawer. Ten cards, ranked by what they could save you:

• Cache health — how much of your context is re-read cheaply versus re-uploaded at full price
• Most expensive queries — the top five, with a jump-to-star link
• Model mix — spend per model, plus small queries running on a top-tier model that could run on a lighter one
• Heavy sessions — sessions whose cost per query runs more than 3× the median
• Subagent share — how much of your spend goes to delegated work
• Same tokens, other models — the whole range re-priced at each tier's rates
• What tools dragged in — the context your tool results carried back, priced at input rates
• Spend per commit — dollars against the commits that landed in the same window
• This week vs last — the trend line
• Last 14 days by project — a per-project sparkline

Options

| Flag | What it does | |---|---| | --dir <path> | Read logs from somewhere other than ~/.claude/projects | | --range <r> | 7d, 30d (default), 90d, or all | | --port <n> | Serve on a specific port (default 4177, auto-increments if busy) | | --demo | Run against the bundled demo dataset — no logs needed | | --no-open | Don't open the browser |

How the cost is computed

Every assistant turn in a session log carries a usage block: input tokens, output tokens, cache reads, and cache writes split by TTL. Costellia prices each one at that model's published rate — cache reads at a tenth of the input rate, 5-minute cache writes at 1.25×, 1-hour writes at 2× — and attributes the total to the user prompt that started the turn. Subagent transcripts roll up into the query that spawned them, and are also reported separately so you can see the split.

A query whose model has no price on file renders as a neutral gray star sized by tokens alone; nothing is guessed. The prices in use are dated in the footer.

Privacy

Everything runs on your machine: a local process reads local files and serves a local page. Nothing is uploaded, and the tool writes nothing at all — it only reads.

The server binds to 127.0.0.1, so the page is reachable from your machine and nowhere else; joining an untrusted network does not expose your prompts or your spend. Credentials pasted into a prompt are masked before they are ever rendered, because prompts end up in screenshots.

MIT licensed.