Skip to main content
plugin CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install usage-engineer@awesome-codex-plugins
Open on GitHub

What 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.md files
  • compare two benchmark runs and spot quality regressions

Example prompts for the agent

  • Run ue audit --by-day and tell me which days cost the most tokens.
  • Compact build.log with ue summarize-log --file build.log and 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-plugins

Step 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`)

[![CI](https://github.com/noamshorts22-prog/usage-engineer/actions/workflows/ci.yml/badge.svg)](https://github.com/noamshorts22-prog/usage-engineer/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
![License](https://img.shields.io/badge/license-MIT-green)

**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

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
waggle The waggle plugin for Claude Code and Codex stores project decisions, constraints and their reasons in a local graph for the agent to use in later sessions. CX Codex ★ 1,596repo stars vibestretch vibestretch nudges you to stretch or rest your eyes during long agent turns. Prompts follow your waiting time, not a fixed timer. CX Codex ★ 1,596repo stars vibe-portrait vibe-portrait reads your AI chat logs and builds an HTML portrait with an MBTI type, a capability radar, a developer rating and a persona skill that thinks in your style. CX Codex ★ 1,596repo stars velith velith takes a book from a blank page to EPUB and PDF through six phases, with twelve agents, a locked voice and a readiness gate before publishing. CX Codex ★ 1,596repo stars unity-agent-workflows The unity-agent-workflows plugin guides AI agents through Unity 2D changes: trace what controls the in-game result before editing, then validate the patch. CX Codex ★ 1,596repo stars unforgit unforgit gives a coding agent a memory store that lives in the repo, so past decisions, conventions, gotchas and playbooks survive between sessions. CX Codex ★ 1,596repo stars tree-ring-memory The tree-ring-memory plugin guides Codex agents through local project memory: recall, evidence-backed notes, audits, consolidation, and explicit forgetting. CX Codex ★ 1,596repo stars tool-advisor tool-advisor reads your MCP servers, skills, plugins and CLI tools, then offers up to three ranked ways to finish the task, each with commands you can copy. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open