Minimize context, not evidence.
Rules
- Never compact the user's current request, acceptance criteria, active constraints, unresolved errors, or uncommitted-change warnings.
- Keep exact commands, file paths, line references, failing test names, error messages, decisions, and latest task state.
- Archive the full source before omitting content. Treat a capsule without a retrievable archive as lossy.
- Prefer targeted reads (
rg, line ranges, structured queries) over reading entire files. - Prefer summaries of successful output; preserve failure output verbatim.
- Retrieve archived lines before acting when a capsule says evidence was omitted and the missing detail could affect correctness.
- Do not reduce verification, skip tests, shorten required code, or stop early to save tokens.
Compact large material
Run the bundled CLI from the project root:
TOKENOP_SCRIPT="${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/token-budget}/scripts/tokenop.py"
test -f "$TOKENOP_SCRIPT" || TOKENOP_SCRIPT="$HOME/.codex/skills/token-budget/scripts/tokenop.py"
python3 "$TOKENOP_SCRIPT" compact PATH
Claude Code sets ${CLAUDE_SKILL_DIR}. Skills CLI installs the shared Codex
copy under ~/.agents/skills; the fallback supports direct legacy installs.
If a command is known or expected to be noisy, compact its first run rather than consuming the raw output and compacting only later. For stdin:
COMMAND 2>&1 | python3 "$TOKENOP_SCRIPT" compact -
Use --max-chars 8000 for routine output and increase it when critical evidence does not fit. Read the emitted capsule instead of the original bulk output.
Work token-efficiently
- Search first, then open only relevant ranges.
- Run independent reads in parallel.
- Do not re-read unchanged files or repeat successful commands.
- Keep one short task ledger: objective, constraints, changed files, unresolved failures, next action.
- After each milestone, replace stale exploration details with verified findings.
- Keep user updates short; spend tokens on implementation and verification.
Recover omitted evidence
Use the capsule's source hash:
python3 PATH_TO_SKILL/scripts/tokenop.py retrieve SHA256 --lines START-END
Retrieve the full source by omitting --lines.
Before finishing
Confirm:
- requested behavior is implemented;
- relevant tests actually ran;
- failures and limitations are stated;
- no requirement disappeared during compaction.
Read references/policy.md only when changing preservation rules or evaluating quality.