usage-audit

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

1. 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.

2. 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.

3. 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)

4. 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.