Ask an LLM about your usage

The dashboard is for you. --summary-json is for whatever you ask about your usage — Claude Code, Codex, Cursor, a script — and is built so a model can take it whole:

ai-usage-tui --summary-json            # the last 7 days, as one line of JSON
ai-usage-tui --summary-json --month --top 20
ai-usage-tui --agent-guide             # how to read it, and what to look for
ai-usage-tui --schema                  # every key and every enum value, defined

--json prints one object per request: 13 MB for the 25,000 requests on the machine this was written on, far more than a context window holds. The summary is the same history in about 33 KB — totals, then the same rollup by_category, by_model, by_project, by_session and by_day, with sources, pricing, burn, every budget (including the ones still OK), limits, escalations, provenance and routing. --top N (default 10) lists the largest models, projects and sessions and folds the rest into other, so a shortened list still adds up.

Every rollup carries figures nothing computed before — cache_hit_pct, tokens_per_request, cost_per_request, output_pct, reasoning_pct, share_of_tokens_pct — and each model its list_input_rate, so which model is the expensive one is a number rather than a guess from its name:

{ "provider": "opencode", "model": "claude-sonnet-5", "category": "PAID",
  "cost_status": "reported", "list_input_rate": 3.0, "sessions": 0,
  "requests": 1, "tokens": 335000,
  "input_tokens": 200000, "output_tokens": 100000, "reasoning_tokens": 20000,
  "cache_read_tokens": 10000, "cache_write_tokens": 5000,
  "cost": 0.5, "cost_is_floor": false,
  "priced_requests": 1, "unpriced_requests": 0, "quota_requests": 0,
  "api_equivalent_cost": null,
  "metrics": { "share_of_tokens_pct": 23.85, "cache_hit_pct": 4.65, "output_pct": 29.85,
               "reasoning_pct": 5.97, "tokens_per_request": 335000.0, "cost_per_request": 0.5 } }

Facts, not advice. There are no thresholds, no verdicts and no “you would save $X”: the tool does not price hypotheticals, and what a cache-hit percentage means for a project is a judgement. That judgement is coached in --agent-guide, which also tells the model what not to claim. And unknown stays unknown here too: a percentage nothing recorded is null, not 0 — several sources never report cache or reasoning tokens — and cost is null when nothing in a rollup could be priced, which on a subscription plan is most of them.

To look closer without pulling every row, pass a value from the summary back as a filter — --project PATH, --session ID, --model NAME, --provider NAME — and take rows only when you need them, as --csv -, which is a quarter of the JSON’s size.

With Claude Code, install the skill and just ask — “how can I cut my token usage?”, “which project is eating my quota?”, “is Opus worth it on this repo?”:

/plugin marketplace add SophanaSok/ai-usage-tui
/plugin install ai-usage@ai-usage-tui

or cp -r contrib/claude-code/plugin/skills/ai-usage ~/.claude/skills/. The skill is three lines long on purpose: it sends Claude to --agent-guide and --summary-json, so the instructions always match the version you have installed. With any other agent, paste the block in contrib/agents/README.md into AGENTS.md, .cursorrules or a system prompt. Details, verification and uninstall are in contrib/claude-code/README.md.

What the model reads — token counts, model names, costs, project paths and session ids — goes to whichever provider it runs on, as anything in its context does. Your prompts and transcripts are never read, and ai-usage-tui itself still sends nothing anywhere.

Let an agent set it up, build on it, or extend it

Reading is the default; the same flag takes a topic for the rest. ai-usage-tui --agent-guide setup is what an agent needs to configure the tool for you — add a budget, switch a source off, install the Claude Code hook or the status line, schedule a timer — and it is written for an agent on a binary install, which has no contrib/ directory to copy from: the hook’s JSON and the systemd units are inside the guide, held to the shipped files by a test.

The tool edits another program’s file in one case only: --install-hook and --install-statusline merge its own entries into Claude Code’s settings.json, when you or an agent run them, and report what they wrote; the guide tells the agent to name the command and the file before running either. Every other change the agent makes by hand, after showing it to you, and --doctor says whether it took. The guide also says which commands write a file or use the network (nothing does by default), that --print-config’s sample budgets are live and must not be saved whole, and that a budget counts dollars — so on a subscription plan it watches nothing, and the agent should tell you that rather than set one up.

--agent-guide recipes is for building on the data: a Waybar module showing the fullest plan window, a guard that stops a batch job before a rate limit, a budget alert on a schedule, a weekly digest, a per-project table, rows into SQLite. It says what is stable enough to script against (the JSON and CSV outputs, exit codes, flags) and what is not (anything meant for eyes), and carries the reading rules into code — in jq, .cost // 0 turns an unknown into a zero nobody can see. Every recipe that needs only jq is run by the test suite, as written, against fixture data.

--agent-guide extend is for what the tool lacks. Usage from a tool it does not read goes through --record-event and a few lines of jq, with no change here; the guide has the keys, a worked adapter, and the rule that outranks the request — if the tool does not measure its token counts, there is no row, and saying so is the answer. For a change to the source it sends the agent to this repository’s AGENTS.md and CONTRIBUTING.md, or to the issue template.

You do not need to mention any of this when you ask. The skill and the pasted block only ever say “run --agent-guide”; that guide lists the topics, so an agent finds them on a version that has them and is not sent to one that does not.