Codex Token Guard

Codex Token Guard is a plug-and-play Codex plugin that cuts noisy context and tool-output tokens during Codex sessions while preserving task-critical details.

It is built for long coding sessions where broad shell commands, huge logs, dependency output, repeated stack frames, and oversized file reads can waste context without helping the task.

What It Does

• Blocks or warns on high-noise commands before they run.
• Suggests cheaper alternatives such as rg, targeted tests, and bounded reads.
• Compresses noisy command output after tools run.
• Preserves errors, stack traces, file paths, line numbers, test names, API names, function names, user instructions, recent edits, and architecture decisions.
• Tracks estimated raw tokens, sent tokens, saved tokens, blocked commands, compressed outputs, quality flags, and session summaries.
• Shows macOS notifications when session-scale savings cross meaningful thresholds.

Default rule: quality beats savings. If Token Guard is uncertain, it preserves the content.

Install From GitHub

After the repository is public, install it as a Codex repo marketplace:

codex plugin marketplace add Davidcreador/codex-token-guard
codex plugin marketplace upgrade codex-token-guard

Then open the Codex plugin browser, choose the Codex Token Guard marketplace, and install codex-token-guard.

Start a new Codex thread after installation so the plugin skill and hooks load. Codex may ask you to review and trust the bundled hooks the first time they run.

Install From Source

git clone https://github.com/Davidcreador/codex-token-guard.git
cd codex-token-guard
npm install
npm run build
npm run validate:plugin
node dist/src/cli.js init

For local development, hooks/hooks.json contains the lifecycle hook configuration and .codex-plugin/plugin.json contains the plugin manifest. Use plugin-bundled hooks by default. Manual ~/.codex/hooks.json wiring is only for development without the plugin install, and should not be enabled at the same time as the plugin.

Commands

If you are running from a source checkout, use node dist/src/cli.js in place of codex-token-guard unless you have linked or globally installed the package.

codex-token-guard init
codex-token-guard install
codex-token-guard mode safe
codex-token-guard mode balanced
codex-token-guard mode aggressive
codex-token-guard notifications on
codex-token-guard notifications off
codex-token-guard notifications status
codex-token-guard notifications in-thread on
codex-token-guard notifications in-thread off
codex-token-guard digest on
codex-token-guard digest off
codex-token-guard digest status
codex-token-guard stats
codex-token-guard stats --session
codex-token-guard snapshot
codex-token-guard restore
codex-token-guard benchmark

codex-token-guard stats prints a metrics summary and writes a visible dashboard to .codex-token-guard/runtime/dashboard.md. Use codex-token-guard stats --session for the current session slice after the latest Stop event.

Modes

• safe: only blocks obvious waste.
• balanced: default mode; blocks high-noise reads, warns on broad tests, and compresses noisy output.
• aggressive: stricter budgets and stronger blocking.

Notifications

Notifications are enabled by default. They show Token Guard's estimated avoided, raw, and sent-token totals for blocked commands, large output-compression wins, benchmark summaries, and stop summaries.

These numbers are not the Codex context-window UI. Codex may count hidden system context, cached items, old transcript entries, or pre-hook accounting that Token Guard cannot read. Treat notifications as Token Guard savings estimates, not as live UI meter readings.

Token Guard also emits sparse in-thread notices at meaningful thresholds. These are intentionally one line, for example:

[token-guard] est. avoided 30k tokens (25%); guard sent 90k of 120k raw · session; blocked 3; compressed 8

The one-line notice is added only for larger savings so the notification itself does not become context noise.

Context Digest

Context Digest is enabled by default. On UserPromptSubmit, Token Guard can add a small read-only digest to large prompts, resume-style prompts, or long sessions after enough hook activity has happened since the last digest.

It is intentionally sparse. It does not run every turn, and it does not replace Codex's own /compact; it gives the model a bounded reminder of the goal, status, decisions, files, errors, and next steps when that context is likely to matter.

Disable it with:

codex-token-guard digest off

By default, notifications start at 5,000 estimated saved tokens and repeat at 5,000-token milestones, so a session that saves around 30k tokens produces a small number of meaningful notices instead of tiny alerts.

Disable them with:

codex-token-guard notifications off

Disable only the in-thread notice with:

codex-token-guard notifications in-thread off

Metrics

Token Guard stores local metrics as JSONL in:

.codex-token-guard/runtime/metrics.jsonl

It tracks:

• estimated raw, sent, and saved tokens
• savings percentage
• blocked and rewritten commands
• compressed outputs
• raw and compressed output tokens
• compression ratio
• session duration
• quality flags

Runtime telemetry files are ignored by git and excluded from release artifacts. Tracked files under .codex-token-guard/ are starter templates only; live hook state is written under .codex-token-guard/runtime/ so normal sessions do not dirty a repository.

Troubleshooting

If /hooks shows hook returned invalid ... JSON output, the hook response was rejected by Codex and that hook result was probably ignored. Update Token Guard to the latest release and restart Codex.

If each Token Guard hook appears twice, check whether both the plugin and ~/.codex/hooks.json have Token Guard installed. Codex runs matching hooks from all active sources, so keep either the plugin-bundled hooks or the manual user-level hooks, not both.

Benchmarks

Run:

codex-token-guard benchmark

The benchmark compares vanilla output against Token Guard behavior and writes:

benchmarks/results/report.md

The MVP target is 20-40% fewer wasted tokens with near-zero quality loss.

Release Artifacts

Tagged releases publish:

• codex-token-guard-vX.Y.Z.tar.gz: Codex plugin bundle.
• codex-token-guard-X.Y.Z.tgz: npm package tarball.
• SHA256SUMS: checksums.

Maintainers can cut a release with:

npm run release:prepare -- 0.2.0
npm test
npm run validate:plugin
npm run release:check
npm run package:plugin
git add package.json package-lock.json .codex-plugin/plugin.json
git commit -m "Release v0.2.0"
git tag v0.2.0
git push origin main --tags

See docs/RELEASE.md for the full process.

License

MIT