audit-usage
Reads the execution trail across runs: billable tokens per skill and agent, duration, failures, permissions, and which report to open next.
audit-usage, section by section
The sections of the skill's own SKILL.md, excerpted. Hover or click one to see which project rules, templates and references/ files it cites. The sections are also chips: click one to jump to it.
## Consolidated trail
!java "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/ArchHook.java" audit summary 2>&1
Everything below reads. This skill never writes into .claude/audit-usage/ and never edits project code — the trail is written by ArchHook.java audit, at Stop, and by nothing else.
Answer in English, the language of the reports themselves, so the consolidated view and the per-run report read as one document. Reports and ledger rows written by an older hook are in Portuguese (✅ sucesso); quote them as they are, never translate a number or a status out of them. Reports written before decision 0134 also carry a cost in USD; quote it only from that report, never as a figure of the trail.
## When the block came back empty
The trail is off: .claude/audit-usage/ does not exist, and audit summary prints nothing at all. That is the switch, not a failure. Say so, and give the two commands that turn it on — creating the directory is enough, the hook is already wired in .claude/settings.json:
mkdir -p .claude/audit-usage
printf '.claude/audit-usage/.state/\n' >> .gitignoreThen stop. Do not create the directory yourself: switching a versioned audit trail on is the user's decision, not a side effect of asking what it holds.
If the block says closed runs: 0, no run has finished yet. Any report listed under ⏳ No ledger line is from a run in progress — report it as such and say the ledger line is written only when the run closes.
## What the block already did
ArchHook.java audit summary reads history.jsonl (one line per top-level run) and nodes.jsonl (one line per skill or agent that run chained) and does the arithmetic: totals, spend per piece without double counting, failure rate, and the reports worth opening. The aggregation is Java on purpose — the ledgers grow without bound, and injecting them raw would cost tokens on every read and leave the sums to you.
Never recompute a number the block printed, and never read the .jsonl files to re-derive one. Your job is rendering and judgment, not arithmetic.
What the block's vocabulary means:
… cut here, the rest is in the file
### 1 · Route on the argument
| Argument | Do this |
|---|---|
| empty | § 2 — consolidated view |
last / último | § 3 for the most recent report the block names |
a skill or agent name (new-feature, java-spring-boot-developer, …) | § 2 reduced to that piece's line, then § 3 for its newest report: ls -1t .claude/audit-usage/*--<name>.md when it ran as a root; otherwise the newest run of its line in grep '"skill":"<name>"' .claude/audit-usage/nodes.jsonl — a chained piece's report is its parent's |
| any other text | treat it as a fragment of a report filename (ls -1t .claude/audit-usage); § 3 for the single match. Two or more matches: list them and ask which |
### 2 · Consolidated view
Present the block, in its order, keeping its tables and the text bar chart intact — bars are proportional to billable tokens, not to duration, which is wall-clock and includes time the user spent thinking. Then add what the block can't:
- One line of reading above the tables — where the tokens went, in words.
- Where it went — from the
Where the pieces spentblock, the piece whose calls - Health — name the piece with the worst failure ratio. A piece that fails
- What to read next — the single most relevant report, and the exact
If the plan windows say not configured, say so and point at .claude/audit-usage/plan-limits.json, set with /project-config or java -jar .claude/hooks/ArchHook.jar config set plan-limits pro.five_hour_tokens <n> (and pro.weekly_tokens) — never by editing the JSON, which guard refuses — the billable tokens the person saw a Pro window hold (the audit's total when /usage reached 100%). Never suggest a budget: Anthropic publishes none, and one written from memory looks as authoritative as a measured one. Never convert anything to a currency either: the trail prices nothing, and a rate written from memory is wrong the day after it changes.
### 3 · Single run
Read the .md file. It is already a finished, icon-rich report — do not re-render it and do not paste it back in full. Summarize in at most six lines: what was run, the outcome, its billable tokens, the longest step, where it spent (from 🔎 Where the run spent: the dominant tool, the costliest turn, the peak context), and anything that deserves attention (⏳ in progress, compaction incidents, permissions added, repeated tool failures — quote the error's first line the report already redacted, never more). Then give the path so the user can open the whole thing.
Point out ⏳ in progress when you see it: it means the run never closed — the session was killed, or it is still open right now.
## What this skill will not do
- Never edits or deletes anything under
.claude/audit-usage/. Pruning old reports - Never prices the trail. The numbers come from
audit summary, in tokens; a cost - Never reads
.state/. Those are the hook's open append-only logs; the rendered - Never quotes a redacted value. The reports blank credential-shaped text on the way
## Why this is a skill, and why the hook ignores it
The hook already answers "what happened in this run", and audit summary does the sums across runs. Nothing turns that into "which piece is eating the budget, and which report should I open" — judgment over data, routed by an argument, which is a procedure, not a norm and not enforcement.
audit-usage is one of the skills the trail does not record — the observers: its class, observer in skill_classes of .claude/schemas/extensions.json, declares audited: false, and arch-doctor sits in the same class. Without that, reading the trail would append a report about reading the trail, and every later read would be mostly reads.
Invoking it still closes whatever run is open, and that is the useful half: within a single session a report stays stamped ⏳ in progress until something ends the run, so asking for the report is what finalizes it.
arch-adopt is never recorded either — fixed in its own class override. Any other piece can be switched per project in .claude/audit-usage/audited.json, one of the files of .claude/ the project owns and /arch-adopt never overwrites — through /project-config or java -jar .claude/hooks/ArchHook.jar config set audited skills.<name> false, the only writer; doctor's Audit overrides line validates it.
Runs on sonnet with effort: low: audit summary already did the sums, and what is left is ranking and rendering (@.claude/decisions/0080-procedural-skills-on-sonnet.md).
What it reads, writes and refuses
The skill's own contract, from SKILL.md, in the original wording.
Source: SKILL.md § Contract, at nerviz e4cae27.
What the guard does with it
observer is the skill's class, and the list on the left is its territory. The phase opens when the skill runs on a prompt of its own, and ArchHook judges every write against that list. The text on the right is the hook's own.
write_allow of audit-usage
any file: the territory is empty
A refusal exits with code 2 and the message goes back to the model.
> /audit-usage … UserPromptSubmit guard prompt exit 0 # phase opened: audit-usage (class observer) # write_allow: [] — this class writes no file
PreToolUse Write(pom.xml) guard write exit 2 ❌ `audit-usage` is class `observer` — pom.xml is outside its territory. write_allow: (nothing — this class writes no file) Put the content in the spec as a code block, or finish the run and invoke the skill that owns this path. If the path is legitimately this skill's, widen skill_classes.observer in .claude/schemas/extensions.json — retrying will not help.
Who calls it
It is not a step of a chain. It starts from a prompt of its own, /audit-usage, and the guard treats it like any other skill: the phase opens, and the territory of its class applies.