Claudoscope vs ccusage: which Claude Code usage tracker fits how you work
People ask me this more than any other question about Claudoscope, usually phrased as "isn't this just ccusage with a window?" Fair question. Both tools read the same JSONL files under ~/.claude/projects/, both run locally, both are MIT licensed, and both will tell you what yesterday cost. Past that they were built for different jobs, and I still run both.
The short version
ccusage is a command-line report. You run npx ccusage@latest, it scans your local transcripts, and it prints a table of tokens and estimated cost by day, week, month, session, or 5-hour billing block. It runs anywhere Node or Bun runs, it emits JSON, and it now covers 18 different coding-agent CLIs, from Codex to Gemini CLI to OpenCode. If you want a number in a script, a cron job, or a Grafana panel, ccusage is the right shape.
Claudoscope is a native macOS menu bar app that watches those same files as they change. It keeps a browsable, searchable history of every session, shows cost by project, model, and day, scans transcripts for leaked credentials while the session is still running, fires cost alerts, lints your ~/.claude/ configuration, and exposes a read-only MCP server so Claude Code can query your own usage. It only runs on Apple Silicon Macs, and it is built for people who want the tool to come to them.
What they have in common
Both read ~/.claude/projects/<project>/<session-id>.jsonl. Neither modifies those files. Neither sends anything over the network: ccusage has an --offline flag for cached pricing, and Claudoscope makes no network requests at all. Both are free, MIT licensed, and open source. Both estimate cost from token counts and model pricing, which means neither one is your invoice. More on that below.
Feature comparison
Checked against the ccusage README and docs at ccusage.com on September 29, 2026. If something here is out of date, open an issue and I will fix it.
| ccusage | Claudoscope | |
|---|---|---|
| What it is | CLI, run with npx, bunx, or pnpm dlx | Native macOS app (SwiftUI), lives in the menu bar |
| Platforms | Anywhere Node or Bun runs | macOS 14 or later, Apple Silicon |
| Install | npx ccusage@latest | brew install --cask claudoscope |
| Agents covered | Claude Code plus 17 other CLIs (Codex, Gemini CLI, OpenCode, Amp, Copilot CLI and more) | Claude Code and Claude Cowork |
| Reports | daily, weekly, monthly, session, blocks (5-hour windows), statusline (beta) | Analytics by project, model, and day; cache hit rate; what-if calculator for model swaps |
| Live view | Removed in v18 (blocks --live existed in v17) | Menu bar widget with a live cost figure per running session |
| Browse a session's transcript | No, usage totals only | Yes: full chat view, search, per-edit file diffs, subagent linkage |
| Secret scanning | No | Yes, regex plus entropy, with an on-screen alert while the session is active |
| Cost alerts | No | Four rules: single-session cap, rolling window, daily, monthly |
| Notifications | No | "Claude needs you" and "Your turn", with terminal tab focus |
| Config linting and hardening | No | 85 lint rules, 13 drift checks, one-click reversible baseline |
| Scripting interface | --json on every report | Read-only MCP server with nine tools, so Claude Code itself can ask |
| Cost source | Claude Code's costUSD field when present, otherwise LiteLLM pricing tables; --mode auto, calculate, or display | Per-message pricing tables for Anthropic or Vertex AI, reconciled against real invoices |
| Web search fees | Not included, per the ccusage docs | Billed at a cent per search, read from toolUseResult.searchCount |
| Offline | --offline uses cached pricing | Always offline |
| Config | JSON config files with schema | Settings window, nothing to configure by default |
| Price and license | Free, MIT | Free, MIT |
Where the cost numbers diverge
Run both on the same day and you will usually get numbers a few percent apart. The ccusage docs show this themselves: their cost-modes page has an example day at $12.45 in display mode and $12.38 in calculate mode, from the same transcript. Here is where the gaps come from.
ccusage in its default auto mode prefers the costUSD value that Claude Code writes into some JSONL records, and falls back to computing from tokens when that field is missing. Claudoscope prices every message from its own tables instead, because I wanted one consistent method across old and new transcripts and across the Anthropic and Vertex price lists.
Claudoscope bills web search. Claude Code records the count in toolUseResult.searchCount, and the documented server_tool_use.web_search_requests field is always zero in transcripts. I only found this by reconciling against a real bill. ccusage's docs say tool API calls like web search are not included, so on a research-heavy day it will read low by a cent per search.
Claude Code's JSONL contains partial streaming records with a null stop_reason. Sum every record and you double-count. Claudoscope dedupes these; I shipped that bug once and my estimates ran 1.5 to 2x over the Vertex invoice until I caught it. I have not audited how ccusage handles this, so I will not claim it gets it wrong.
Model families matter too. Claudoscope matches a closed list of the generations that billed at older rates and prices anything unrecognized at the current rate, because a model id it has never seen is more likely new than ancient. ccusage takes its table from LiteLLM and models.dev with historical schedules keyed by timestamp. Both approaches work; they will disagree for a few days after a new model ships.
None of this makes either tool wrong. Your bill is the Console usage page or your cloud provider's invoice. Everything else is an estimate, and both projects say so.
When ccusage is the better choice
Pick ccusage if any of these describe you.
You are not on an Apple Silicon Mac. Claudoscope will not run, and I have no plans to port it.
The number needs to end up somewhere other than a screen: a script, a CI step, a nightly report, a dashboard you already own. ccusage daily --json is exactly that interface, and there is no equivalent in Claudoscope short of asking Claude Code over MCP.
Several agent CLIs are in play and one report across all of them is the goal. Claudoscope only understands Claude Code and Cowork transcripts.
A cost readout in Claude Code's own status line is what you are after. ccusage statusline does that, although Claude Code's built-in status line now has a cost field too.
Another app running in the background is one too many. ccusage runs when you call it and exits.
When Claudoscope is the better choice
Pick Claudoscope if the totals are not the point.
You want to find a session, not just its cost. Search by what you asked, open the transcript, see every file Claude edited with the diffs, jump to the moment it happened.
You want to be told while it is happening: a session burning through a rolling-window threshold, a credential that just landed in a transcript, Claude sitting on a permission prompt while you read something else.
You are on the Enterprise API. There is no per-session spend anywhere in Anthropic's tooling for that setup, and cookie-based trackers cannot see it either. Both ccusage and Claudoscope work there because they read files, but only one of them keeps the history and alerts you.
You care what ended up in those transcripts. Claude Code writes everything it reads into them, including the .env file that started this whole project.
You want to ask in plain language. With the MCP server on, "what did I spend on this project last week, by model" is a prompt in Claude Code, answered from your local data.
Running both
They do not conflict. Both are read-only against the JSONL, and Claudoscope's SQLite index is a separate file, so ccusage never sees it. I keep ccusage around for the --json output and for checking my own numbers against a second implementation. When the two disagree by more than a few percent, one of us has a pricing table bug, and more than once it was me.
Coming from ccusage: what maps to what
| ccusage | Claudoscope |
|---|---|
ccusage daily | Analytics, day view |
ccusage weekly or monthly | Analytics with a date range, or the daily and monthly cost alerts |
ccusage session | Sessions list, sorted by cost |
ccusage blocks | No 5-hour block view. The rolling-window alert (5 minutes to 4 hours) covers the "am I burning right now" case, but if you plan around Anthropic's billing windows this is a real gap |
--project | The project filter above the sidebar |
--json | The get_usage MCP tool |
--mode calculate | The only mode; Claudoscope always calculates |
One more thing ccusage users notice: Claudoscope's first launch on a large corpus does a full parse in the background, then paints from the SQLite cache on every launch after that. On my roughly 3,000 sessions across 74 projects that is sub-second once the cache exists.
Install
Free, MIT licensed, macOS 14 or later on Apple Silicon:
brew tap cordwainersmith/claudoscope
brew install --cask claudoscopeOr take the DMG from the releases page. If you decide ccusage is the better fit, it is at ccusage.com and I mean that without any edge to it.