| name | usage-audit |
| description | Use when the user asks for a usage audit, a "how am I using Claude Code" review, or a usage retrospective, or wants to mine past sessions for tool mix, error hotspots, model spend, repeated prompts, or automation candidates. Not for auditing a single live session, and not a substitute for the metrics dashboard. |
| tools | Bash, Read, Write, Grep, Glob |
Produce an evidence-based audit of how Claude Code is actually being used on this
machine, and turn the findings into concrete recommendations.
Steps
-
Collect data. Run the parser (stdlib-only, read-only over transcripts):
python .ai/scripts/usage_audit.py --days 30
Options: --days N, --project <substring>, --json <path> (raw aggregates),
--top N. Output is markdown; tokens that look like secrets are redacted.
-
Cross-check this repo's own ledgers when auditing the workflow itself:
.ai/local/ledgers/metrics.jsonl (phase dispatches), skill_metrics.jsonl,
events.jsonl. Note: headless dispatch sessions (≤1 user message) are pipeline
traffic, not human sessions — report them separately.
-
Synthesize the report as usage-audits/USAGE-AUDIT-<date>.md under the
.ai/local/ bucket (the repo root only on explicit request — keeps generated
audits out of the versioned tree, per the .ai/local/ convention) with sections:
- What's going right (with counts)
- What's going wrong (error taxonomy with counts and root causes)
- Efficiency opportunities (model tiering, session hygiene, config)
- Skills to create (each backed by ≥2 repeated prompts or a frequency count)
- Skills/automation to improve
- Config quick wins (settings, hooks, allowlists)
-
Every recommendation must cite its evidence (a count, an error string, or a
repeated prompt). No generic advice.
Caveats
- Wall-clock session durations include idle time; don't present them as active time.
- Settings files (
settings.json) usually cannot be auto-edited under auto mode —
present ready-to-paste snippets instead of retrying denied writes.
- Never paste unredacted tokens or user prompts containing credentials into the report.
