# Usage Audit

> Cross-client token and session accounting. Every AI agent client records what it consumed — Claude Code per-message usage JSONL, Codex token_count events, OpenCode per-session token columns — but none shows the cross-client total. Reads the same local stores as session-handoff (read-only, nothing uploaded) and reports tokens by model, client, and project, with an optional budget gate.

- Skill: `trac3r00/usage-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add trac3r00/usage-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/trac3r00/usage-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: trac3r00 (https://skillmd.com/u/trac3r00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/trac3r00/usage-audit

---


# Usage Audit

You cannot manage what no client will show you: cross-client, cross-project
token consumption, from the logs already on your disk.

## Commands

```bash
python3 scripts/usage_audit.py                        # last 30 days, by model
python3 scripts/usage_audit.py --by project           # where tokens go
python3 scripts/usage_audit.py --by client --since 7  # which client burns most
python3 scripts/usage_audit.py --budget-tokens 50000000 || notify  # tripwire
python3 scripts/usage_audit.py --json                 # full report, all groupings
```

## Stores read (read-only, local)

| Client | Source |
|---|---|
| Claude Code | `~/.claude/projects/*/*.jsonl` per-message `usage` blocks |
| Codex | `~/.codex/sessions/**/rollout-*.jsonl` final `token_count` totals |
| OpenCode / OMO | `opencode.db` session token columns |

Missing stores are skipped silently. Cache tokens are tracked separately from
input/output so cached-heavy workflows read honestly.

## Pairs with

`context-budget` (why is per-turn cost high) answers the static question;
`usage-audit` answers the historical one (where did tokens actually go).
`session-handoff` shares the same store-reading conventions.