usage-engineer — Claude Code and Claude Code plugin: token audit
usage-engineer is a plugin for Claude Code and Codex that tracks session token use, compacts long logs and checks whether project maps are current. It also detects repeated command failures.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install usage-engineer@awesome-codex-pluginsWhat usage-engineer does
ue is one Python file, with no dependencies, and it never touches the network. It shows where agent work gets thrown away: oversized logs pushed into context, the same failing command retried, project maps that no longer match the tree.
audit reads local Claude rollout JSONL, Claude transcripts and the OpenCode database, and --by-day adds a per-day table. summarize-log --file build.log keeps every error line plus surrounding context and stores the byte-exact original next to it. map build and map check version a project snapshot; check exits 1 and lists the files that changed. Writes are opt-in — apply-profile --target codex saves a backup with a SHA-256 record, and rollback refuses to overwrite later edits with exit code 3.
Audit output carries no transcript text, turns your home path into %HOME% and never opens auth.json, cookies or chat logs. A live benchmark will not start without --max-calls and --confirm, because ue caps invocations and cannot cap tokens or spend. In the published first run a prepared context pack cost 30% more tokens on the three cases both variants passed. The tool says so itself.
What it helps with
- cut a build log down to errors and nearby context
- see which days ate the most Claude tokens
- catch a stale project map before resuming work
- find duplicated paragraphs across
AGENTS.mdfiles - compare two benchmark runs and spot quality regressions
Example prompts for the agent
- Run
ue audit --by-dayand tell me which days cost the most tokens. - Compact
build.logwithue summarize-log --file build.logand keep the original. - Check whether the project map is stale with
ue map check, then rebuild it if it is.
How to install usage-engineer
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install usage-engineer@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about usage-engineer
How do I install usage-engineer in Claude Code?
Through the marketplace: run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install usage-engineer@awesome-codex-plugins.
What does usage-engineer do?
It totals token spend from local Claude, Claude and OpenCode sessions, compacts long logs down to error lines, tracks whether the project map is current and finds duplicate rules in AGENTS.md.
Does ue send anything over the network?
No. It runs locally, keeps state in ~/.usage-engineer (change it with UE_STATE_DIR) and leaves auth.json, cookies and chat text alone.
Source text
usage-engineer · MIT
# usage-engineer (`ue`) [](https://github.com/noamshorts22-prog/usage-engineer/actions/workflows/ci.yml)    **Stop paying for wasted agent work.** `ue` is a local CLI that measures and cuts the work coding agents throw away: 5,000-line logs pasted into context, the same failing command retried, stale project maps, duplicated instructions. It works with **Codex CLI**, **Claude Code** and **OpenCode**. - Zero dependencies, one Python file, no network calls, ever. - Never reads `auth.json`, cookies, tokens or chat text. - Never changes your model or reasoning settings. Everything that writes is opt-in and reversible. ## Install ``` pipx install git+https://github.com/noamshorts22-prog/usage-engineer ue doctor ``` Or run from a checkout with `python ue.py <command>` (Windows: `ue.cmd <command>`). ### As an agent skill `ue` also ships as an [Agent Skill](https://agentskills.io) that tells the agent when to use it: long logs go to a file and get compacted, identical failures are not retried, and maps are checked before work resumes. The skill bundles `ue.py`, so nothing else needs installing. | Agent | Install | |---|---| | Codex CLI | `codex plugin marketplace add noamshorts22-prog/usage-engineer` then `codex plugin add usage-engineer@usage-engineer` | | Claude Code | `claude plugin marketplace add noamshorts22-prog/usage-engineer` then `claude plugin install usage-engineer@usage-engineer` | | Any agent (Cursor, Gemini CLI, OpenCode, ...) | `npx skills add noamshorts22-prog/usage-engineer` | The skill itself is [skills/usage-engineer/SKILL.md](https://github.com/noamshorts22-prog/usage-engineer/blob/main/skills/usage-engineer/SKILL.md). ## Two minutes to your first numbers ``` ue audit # where did my Codex/Claude Code/OpenCode usage go? (read-only, redacted) ue audit --by-day # token totals per day, to line up with your quota meter ue summarize-log --file build.log # keep every error, drop the noise, store the full copy ue map build --project . # snapshot the project; `map check` tells you when it is stale ``` ## Commands | command | what it does | writes | |---|---|---| | `audit` | usage baseline from local Codex rollout JSONL, Claude Code transcripts (`~/.claude/projects`) and the OpenCode SQLite DB, with waste signals; `--by-day` adds a per-day table; redacted | optional JSON via `--json-out` | | `summarize-log --file X` | compact view that keeps every failure/error line plus context; stores the byte-exact original and prints its path | `--out` dir | | `prepare-context --project DIR` | small task pack: request, constraints, git commit/diff id, path hashes, verification commands | `--out` md + json | | `map build` / `map check` | versioned project map; `check` exits 1 and lists files when anything changed | map json | | `instructions scan/duplicates/verify` | AGENTS.md inventory, paragraph-level duplicate mapping, mandatory-rule verification | optional json | | `compare --a R1 --b R2` | per-task paired comparison of two bench runs; refuses non-comparable records; flags quality regressions | stdout | | `apply-profile --target codex` | opt-in Codex profile `$CODEX_HOME/usage-efficient.config.toml`, used via `codex --profile usage-efficient` | profile + backup + registry | | `apply-profile --target opencode-project --project DIR` | project `opencode.json` that references the ue instructions (aborts if one exists) | project file | | `rollback --target codex` | restores the original state; aborts if the file changed after apply | - | | `bench list/plan` | the 4 frozen paired benchmark cases and the exact commands (no model calls) | stdout | | `bench run --runner codex --max-calls N --confirm` | opt-in live A/B run with a hard invocation cap and no automatic retries | state dir | | `doctor` | environment check: versions, config paths, profiles | stdout | | `selftest` | 39 deterministic tests, no model calls | - | ## Measure before you believe Efficiency claims about agents are cheap. `ue bench` makes them testable: each of the four frozen cases (off-by-one bugfix, cross-file rename, regression test, RTL layout fix) runs in a fresh isolated copy, the agent never sees the solution or the acceptance script, and `ue compare` refuses to compare runs that used different models, reasoning levels or case versions. ``` ue bench plan ue bench run-all --runner codex --max-calls 8 --confirm ue compare --a <baseline-run.json> --b <profile-run.json> ``` ### First live result (2026-10-21, n=1 per cell, codex-cli 0.163.0, default model) A = baseline, B = `context-pack` (a prepared project map handed to the agent up front). | Case | A total tokens | B total tokens | A pass | B pass | |---|---:|---:|:-:|:-:| | bugfix-offbyone | 325,468 | 364,474 | yes | yes | | crossfile-rename | 286,107 | 281,159 | yes | yes | | regression-test | 294,160 | 266,461 | yes | no* | | rtl-cart | 296,432 | 535,727 | yes | yes | On the three cases both variants passed, B used **30% more** tokens (+273,353), mostly cached input. So on these small fixtures the context pack does not pay for itself, and `ue` does not claim it does. One sample per cell is noise-level; treat this as a demonstration of the method, not a verdict. \* B's failure was environmental: the file the agent wrote under the Codex Windows sandbox was not readable by the acceptance script (`PermissionError`), so it says nothing about B's quality. ## Safety properties - Audit output never includes transcript text and redacts your home directory as `%HOME%`. - Unknown metrics are reported as `UNKNOWN` / `null`, never as `0`. - `apply-profile` backs up any existing file and records its SHA-256; `rollback` refuses to overwrite later edits (exit code 3). - `apply-profile --target opencode-global` is refused by design. - Benchmarks refuse to run without `--max-calls` and `--confirm`. `ue` caps the number of invocations; it cannot cap tokens or money. State lives in `~/.usage-engineer` (override with `UE_STATE_DIR`). ## Known limitations - Model-level efficiency is barely measured: one live run per cell so far (see above). Live runs cost quota, so results from your machine are very welcome. - On Windows, files the agent creates inside the Codex sandbox can be unreadable to the acceptance script, which then reports a false failure. - Token figures derived from character counts are estimates (4 characters per token). - The OpenCode audit covers `session` table totals, not per-message parsing. - Claude Code reports uncached input separately from cache reads and writes, so its `input` column is not comparable to Codex's, where cached input is a subset of input. Claude Code totals are tokens, not your plan's usage-limit units. ## Roadmap - Claude Code support in `bench`; Gemini CLI and Aider support in `audit` and `bench` - A GitHub Action that posts `ue audit` waste signals on agent-authored PRs - More benchmark cases, contributed by the community Contributions welcome: see [CONTRIBUTING.md](https://github.com/noamshorts22-prog/usage-engineer/blob/main/CONTRIBUTING.md). ## License MIT
© noamshorts22-prog · MIT · hashgraph-online/awesome-codex-plugins