codegraph vs ccusage: the tool and the instrument

Part of the reduce Claude Code token usage pillar. This page pairs a tool that acts with the tool that tells you whether the acting worked.

Is codegraph or ccusage what I need?

Both, in that order of importance and the opposite order of installation. ccusage measures and changes nothing. codegraph indexes your code and changes how the agent works. You install the meter first because codegraph makes a specific, checkable claim, and checking it is more valuable than believing it. That claim is −35% cost and −71% fewer tool calls, median across seven repositories. It is the strongest published number in this category. It is also a vendor median over a sample, with visible run-to-run variance — codegraph's own reporting shows a four-run spread on Tokio. On my open long-session benchmark, codegraph lands at roughly break-even on cost. I run that benchmark and sell a competing tool, so the useful thing here is not my number or theirs. It is your number.

What does ccusage actually do?

It reads your agent's local JSONL transcripts and reports what you spent. Roughly 15k stars, 15 supported agent sources, zero install — bunx ccusage or npx ccusage@latest. Daily, weekly, monthly and per-session reports, per-model breakdown, cache token tracking, and JSON output that composes with other dashboards. For Claude Pro and Max subscribers the standout is the 5-hour billing block view: Anthropic's limits roll on a five-hour window, and ccusage shows where you are inside it rather than after it. Its limits are stated plainly. It is read-only and reduces nothing, and it has no counterfactual — no "what would I have spent without tool X" view. The JSONL schema it reads is implicit rather than specified, so it reports what agents happen to write.

What does codegraph actually do?

It replaces file-hunting with a query. tree-sitter parses your source into an FTS5 SQLite knowledge graph served over MCP, covering 20-plus languages and 14 frameworks: impact analysis, call graphs, symbol lookup. The agent asks where a function is used instead of opening four files to find out. It is the easiest install in the category. A bundled Node.js runtime removes version management, and an interactive installer detects eight agents and writes their MCP config itself. The debounced file watcher shows a staleness banner when files are pending re-index, so the agent knows when its answer may be behind the working tree. Its gaps: no output filtering, so verbose shell output still arrives at full size; FTS5 keyword search only, with no semantic retrieval; no deferral of MCP manifests — and codegraph adds one of its own; no compression of the files the agent opens to edit.

How do you actually verify the −71%?

Count tool calls, not tokens, and do it over comparable work. Tool calls are the right metric because they are what an index mechanically changes. Cost is downstream: it depends on what the agent does with the navigation it no longer needs, which is why the same tool shows large variance across runs on the same repository. A workable procedure:

One week without codegraph. Record daily spend and, where your agent exposes it, tool-call counts.
Install codegraph and index the repository. Change nothing else that week — not your model, not your other MCP servers, not your prompting habits.
One week with it. Compare like for like.
Read the split, not just the total. If tool calls dropped and cost did not, the index is working and your spend lives somewhere else.

That last outcome is the common one, and it is informative rather than disappointing. It tells you your tokens are in command output, in the files the agent opens to edit, or in conversation history — three channels an index does not touch.

What does the meter see that no optimizer reports?

Cache tokens, and the per-model split. Both are in ccusage and neither appears in any optimizer's own reporting, including codegraph's. Cache tokens matter because cached input is billed at a fraction of fresh input on every major provider, which makes cache-hit rate the single largest lever on a long session. A tool that quietly lowers it can cost you more than it saves in raw token count, and you would never see that in a "tokens saved" counter. An index like codegraph does not touch the prompt prefix, so it is safe on this axis — but that is a property worth confirming rather than assuming, and confirming it needs the meter. The per-model split matters for a different reason. If one model is draining far faster than the others, the cheapest fix is routing, not optimisation: send the cheap work to the cheap model. That decision costs nothing to implement and it is invisible without a breakdown. There is a third thing the meter gives you that no benchmark can: your own baseline variance. Two ordinary weeks of work rarely cost the same. Knowing how much your spend moves on its own tells you how large an effect has to be before you can claim to have seen it — and it is usually larger than people assume, which is why single-session comparisons produce confident nonsense.

What can the meter not tell you?

Why. ccusage reports that a session cost more than usual. It will not tell you that eleven of your last twenty tool calls re-read the same four files, or that a stale index sent the agent down a wrong path. It also cannot isolate a variable you did not isolate. Two changes in one week produce one uninterpretable result, and this is the single most common way a measurement week is wasted.

Which one should you pick?

Install ccusage regardless. Free, zero-install, read-only. There is no scenario where knowing the number leaves you worse off, and every other decision on this page depends on it. Install codegraph if the agent spends its time finding things in a large codebase, or if you want the lowest-friction install to put in front of a team. Then verify it rather than trusting the median. Do not install codegraph expecting it to help a build-and-test loop. It is not on that path at all, and no amount of indexing changes that.

How to apply this today

Run npx ccusage@latest now. Seconds, no install, reads transcripts you already have.
Write down your baseline: input/output ratio, cache-hit rate, per-model split, daily total.
Change one thing. Then read the meter a week later, not a task later.
Judge the index on tool calls. That is what it moves; cost is a downstream effect with more variance than most people expect.

What goes wrong (anti-patterns)

Installing the optimizer before the meter. You then have an opinion instead of a result. Reading a vendor median as your outcome. −35% is a good-faith figure over seven repositories. Yours is one repository. Changing two things in the same week. The most reliable way to learn nothing. Treating ccusage as an optimizer. It saves nothing at all. Its entire value is what you do with the number.

See also: