A Codex plugin for professional brevity, selective model routing, and bounded agent collaboration.
It keeps ordinary coding work in the main thread. It delegates only when a faster read-only scout can isolate noisy context, a deep worker is justified by implementation complexity, or a deep reviewer is justified by material risk.
- Uses concise, complete professional sentences.
- Avoids repeated facts, routine tool narration, and oversized raw logs.
- Preserves code, errors, safety warnings, public interfaces, and requested detail.
- Routes bounded lookup work to gpt-5.6-terra with low reasoning.
- Routes difficult implementation and high-risk review to gpt-5.6-sol with high reasoning.
- Keeps task ownership and final decisions in the main thread.
- Prohibits recursive fan-out and overlapping writers.
Codex still decides when delegation is justified. A spawn-only hook routes delegated tasks to the installed scout, worker, or reviewer profile, including on managed surfaces that hide the agent selector. The hook does not directly spawn agents, intercept ordinary tools, or add model context.
- Node.js 20 or newer.
- A current Codex CLI with plugin and hook support.
Clone the repository and add it as a local marketplace:
git clone https://github.com/NearlCrews/token-shaver.git
cd token-shaver
codex plugin marketplace add "$PWD"
codex plugin add token-shaver@personal
Review and trust the hook with /hooks, then start a new thread.
The plugin works in brevity-only mode immediately. Automatic agent model routing requires one explicit setup:
npm run profiles -- install
Or ask Codex:
Set up the TokenShaver agents.
The installer writes only namespaced profiles under CODEX_HOME. It does not edit config.toml.
The routing hook uses task semantics. Clearly read-only lookup goes to the scout, mutating or ambiguous work goes to the worker, and non-mutating high-risk review goes to the reviewer. Explicit model or non-plugin agent choices are preserved.
npm run mode -- on
npm run mode -- off
npm run mode -- status
npm run profiles -- doctor
Project-scoped profiles are also supported:
npm run profiles -- install --scope project --project /absolute/project
Override current model defaults when needed:
npm run profiles -- install --fast-model MODEL --deep-model MODEL
| Profile | Default model | Purpose |
|---|---|---|
| token-shaver-scout | gpt-5.6-terra, low | Read-only lookup, test discovery, scans, and log extraction |
| token-shaver-worker | gpt-5.6-sol, high | Ambiguous, cross-file, migration, and integration implementation |
| token-shaver-reviewer | gpt-5.6-sol, high | Security, concurrency, compatibility, public API, and risky review |
If a configured model is unavailable, routing degrades once to a built-in agent or the main thread. High-risk work must not silently use a weaker reviewer.
Profile installation is idempotent and hash tracked. The installer refuses unmanaged collisions and modified managed files unless --force is explicit. Forced replacements are backed up.
Remove managed profiles before removing the plugin:
npm run profiles -- uninstall
codex plugin remove token-shaver
Use --restore-backups during profile uninstall only when you intentionally want forced-replacement backups restored. Plugin removal and profile removal are separate operations.
npm ci
npm run verify
The repository validates plugin metadata, marketplace metadata, skill metadata, hook shape, profile contracts, committed writing rules, and installer behavior.
Live benchmarks are opt-in because they consume model usage:
npm run benchmark -- --config /absolute/arms.json
npm run benchmark -- --config /absolute/arms.json --execute
npm run benchmark:analyze -- benchmark-results
See HONEST-NUMBERS.md before publishing token or cost claims.
See the contribution guide, security policy, and Code of Conduct.
Apache-2.0