ccusage vs graphify: did the graph even get used?

Part of the reduce Claude Code token usage pillar. This pair is about a failure mode that looks exactly like a tool not working.

Is ccusage or graphify what I need?

ccusage first, because graphify's main risk is not that it fails — it is that it never runs. graphify is invoked by a /graphify slash command. Unlike an MCP server, whose tools sit in the agent's toolbox from the first message, a slash command is consulted only when something in the session steers it there. An index nobody queries costs the indexing pass and saves nothing. From the outside that is indistinguishable from a tool that does not work, and the only way to tell the two apart is to look at the numbers. I maintain an open long-session benchmark and sell a competing tool. graphify shows no measurable session-cost saving on it, and this consultation question is part of why.

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, matching Anthropic's rolling window. It is read-only and reduces nothing, and it has no counterfactual — observed spend only. The JSONL schema it reads is implicit rather than specified.

What does graphify actually do?

It maps the whole project into a queryable knowledge graph. Python, MIT, installed from PyPI, invoked with /graphify across Claude Code, Codex, opencode, Cursor, Copilot, Aider, OpenClaw and others. Its differentiator is what it ingests: documentation, PDFs, images and video alongside source. Nothing else in this category covers non-code assets, and in projects where design documents or recorded handovers hold the answers, that is a genuine gap filled. It produces a persistent artefact — graph.json, plus an HTML view and a Markdown report — so the graph can be queried later without re-reading the codebase, and a human can audit the HTML rather than trusting it blind. Its costs: indexing is an explicit step you re-run as the project moves, a stale graph misleads quietly rather than failing loudly, it needs a Python runtime, and it does not touch command output.

How do you tell whether the graph is working?

Three signals, in order of how easy they are to read:

Tool calls per session. An index that is being consulted reduces navigation reads. If your tool-call count is unchanged after installing graphify, the graph is not in the loop, regardless of how good it is.
Total spend, over weeks not tasks. ccusage gives you this plus your own week-to-week variance, which is usually larger than people expect. A 15% difference against a 20% natural swing is not a finding.
The graph artefact itself. graphify writes graph.json and an HTML view. Open it. If it is stale, or missing the documents you assumed it covered, you have found the problem without needing any usage data at all.

That third signal is graphify's own advantage and it is worth using: most tools in this category give you nothing to inspect.

What it costs when it is not consulted

The indexing pass, and nothing else — which is the good news. graphify is opt-in, so unlike an always-connected MCP server it does not charge you a manifest on every turn. An unconsulted graph is wasted effort rather than an ongoing bill. That is a materially better failure mode than the alternative, and it is worth knowing before you conclude the tool was a mistake. The fix is usually one line. Put the invocation in your project instructions so the agent reaches for the graph when a question is about project structure. Without it, you have installed the tool rather than adopted it.

What can the meter not tell you?

Why. ccusage reports that a session cost more or less than usual. It will not tell you that the agent ignored the graph, that the graph was three weeks stale, or that eleven of twenty tool calls re-read the same four files. It also cannot isolate a variable you did not isolate. Two changes in one week produce one uninterpretable result — and re-indexing counts as a change.

Which one should you pick?

Install ccusage regardless. Free, zero-install, read-only, and here it is what separates "graphify did not help" from "graphify never ran". Install graphify if your project's knowledge is not all in the source — architecture documents, specifications, vendor PDFs, recorded handovers. Then write the invocation into your agent instructions rather than hoping. Skip graphify if your repository is pure code with a thin README. Its differentiator does not apply to you and a source-only index will be simpler to keep fresh.

How to apply this today

Run npx ccusage@latest and record four normal weeks. That is your variance baseline, and it is the thing most comparisons are missing.
Open graph.json or the HTML view after your first indexing pass. Confirm it contains what you assumed.
Write /graphify into your project instructions, tied to the kind of question it should answer.
Judge it on tool calls first, cost second.

What goes wrong (anti-patterns)

Installing an opt-in tool and never invoking it. The most common failure here, and it looks identical to the tool being useless. Re-indexing and changing something else in the same week. One uninterpretable result. Trusting a stale graph. Confident wrong answers cost more than no answer, and graphify does not warn you the way a watcher-based index does. Treating ccusage as an optimizer. It saves nothing. Its whole value is what you do with the number.

See also: