| name | token-guard |
| description | Use Codex Token Guard to reduce noisy command and tool-output tokens while preserving errors, file paths, line numbers, test names, user instructions, recent edits, and architecture decisions. |
Codex Token Guard
Use this skill when a Codex session needs lower token waste without lower output quality.
Operating Rule
Default to quality over savings. If uncertain, preserve content.
Workflow
- Prefer focused search and reads:
rg --files | sed -n '1,200p' instead of find .rg "pattern" path/ instead of grep -rsed -n '1,160p' file.ts instead of cat on large files
- Keep full error context:
- actual error message
- file path
- line and column
- failing test name
- stack frame where useful
- Use CLI checks:
codex-token-guard statscodex-token-guard stats --sessioncodex-token-guard snapshotcodex-token-guard benchmarkcodex-token-guard notifications statuscodex-token-guard digest status
- Before compaction, preserve:
- goal
- current status
- key decisions
- files touched
- bugs/errors
- next steps
Modes
safe: only blocks obvious waste.balanced: default; blocks high-noise reads, warns on broad tests, compresses noisy output.aggressive: strict budgets and fail-closed hook errors.
Quality Protection
Never remove user instructions, recent edits, architecture decisions, actual error messages, file paths, line numbers, API names, function names, or test names.
Notifications
Notifications are on by default. They show Token Guard estimated avoided, raw, and sent-token totals for blocked commands, output compression above the configured threshold, benchmark results, and Stop summaries. They are not Codex context-window UI readings.
Runtime metrics and session state live under .codex-token-guard/runtime/ so hooks do not edit tracked starter templates.
In-thread notices are enabled by default and stay one line at milestone scale:
[token-guard] est. avoided 30k tokens (25%); guard sent 90k of 120k raw.
Context Digest is enabled by default. It injects a small session digest only on resume-style prompts, large prompts, or long sessions after enough hook activity since the last digest. It should not run every turn.
If /hooks reports invalid JSON output, update Token Guard and restart Codex. If hooks appear twice, remove either the manual ~/.codex/hooks.json Token Guard entries or the plugin-bundled install so Codex does not run both.
Use:
codex-token-guard notifications statuscodex-token-guard notifications oncodex-token-guard notifications offcodex-token-guard notifications in-thread oncodex-token-guard notifications in-thread offcodex-token-guard digest oncodex-token-guard digest offcodex-token-guard digest status
