claude-usage-audit
Skill0 starsChanged 10 days agoApache-2.0View on GitHub
Use when asked to analyse Claude Code token usage or spend over a period, or to re-measure after a cost change: "analyse mon usage token", "combien j'ai consommé", "pourquoi je tape la limite". Not for API pricing or model choice (claude-api).
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- addressing-gitlab-review-commentsSkill
- auditing-mobile-layoutSkill
- charting-grafana-metricsSkill
- confluenceSkill
- gitlab-job-triageSkill
- grafana-cloud-monitoringSkill
- grafana-dashboardsSkill
- handoffSkill
- incident-responseSkill
- jira-cliSkill
- k8s-rightsizingSkill
- mr-openSkill
- pixibixi-wiki-articleSkill
- rss-digestSkill
- scoping-a-websiteSkill
- tf-module-releaseSkill
- ticket-conventionsSkill
- wiki-fact-checkSkill
The file
Files
Claude usage audit
Four local scripts over ~/.claude/projects/**/*.jsonl (main sessions and subagents/). Each API call is deduplicated on (message.id, requestId); cost is the public API price per model, so on a subscription it reads as "API-equivalent", a proxy for plan quota.
Run
SKILL_DIR="${CLAUDE_SKILL_DIR}/scripts"
OUT=$(mktemp -d) # or the session scratchpad
python3 -I "$SKILL_DIR/usage.py" "$OUT/usage.json" # totals, daily, models, projects, sessions, cache rebuilds, tools, skills, agents
python3 -I "$SKILL_DIR/context_sources.py" "$OUT/usage2.json" # Bash command families by output size, full vs partial Read, sdk entrypoints, idle gaps
python3 -I "$SKILL_DIR/cost_split.py" # cost by token type, cache-read tax above 200k / 300k context
python3 -I "$SKILL_DIR/history.py" "$OUT/hist.json" # weekly prompts, cost per prompt, slash commands, sessions, hour x weekday (default 90 days)Window: AUDIT_DAYS=90 in the environment (default 30, 90 for history.py). Transcripts only go back cleanupPeriodDays (set to 120 in settings; Claude Code defaults to 30), while ~/.claude/history.jsonl keeps every prompt: beyond the retention, only prompt-level metrics are real. Mark weeks whose transcripts were partly deleted as partial, never as low-cost.
Before quoting dollars
Prices live in one table, PRICES in scripts/prices.py. Check it against the claude-api skill first. A script that met a model missing from it prints a warning and exits 2: its totals undercount, so add the model and rerun before quoting a figure.
What to look at, in order
| Signal | Field | Lever |
| Calls above 200k context | ctx_cost, cost_split.py tax | autoCompactWindow in settings, /clear per topic |
| Cold resumes (cache rebuilt after >1h idle) | cache_miss | cold-resume-guard.sh hook |
Non-CLI entrypoints (sdk-py, sdk-cli) | entry, sdk in usage2 | a plugin or hook spawning Claude: pin its model (SG_AGENTIC_MODEL for security-guidance) |
| Biggest tool outputs | tool_result_kchars, bash_fam, read | targeted Read, capped command output |
| 1h vs 5m cache TTL | w1h vs the 5-60 min gap count in gaps | keep 1h while 5-60 min gaps x context x 1.25 exceeds the 0.75x premium on 1h writes |
| Subagent share and model | main_sub, agents | Sonnet for pattern work |
Session prompts in top_sessions are the user's own text: keep them out of anything shared.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.