Token OptimizerBLOCK

Find the ghost tokens. Fix them. Survive compaction. Avoid context quality decay.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: token-optimizer
description: Audits a Claude Code or Codex setup for context-window waste, fixes it with the user's approval, and measures the saving. Use when context feels tight, sessions degrade, or costs climb.
effort: high
---

# Token Optimizer

Measures where a setup spends its context window, proposes fixes, applies the ones the user approves, and re-measures. The deliverable is a before-and-after the user can verify, with every change backed up. Typical recovery is 5-15% of the window from config cleanup, more when compaction and caching settings are wrong for the way the user works.

Token Optimizer's own skills (`token-optimizer`, `token-coach`, `token-dashboard`, `fleet-auditor`, `resume-checkpoint`) are the measurement layer, so leave them out of every unused-skill, archive or consolidation suggestion, however rarely they run.

## Step 0: pick the right workflow for this runtime

The audit below reads and edits `~/.claude`, which is the wrong target anywhere but Claude Code, so settle the runtime before touching any path. Run exactly this, in this order.

**a. Environment check** (touches no file; an explicit `TOKEN_OPTIMIZER_RUNTIME` wins, and Claude plugin variables are checked before stray `OPENCODE_*` exports, the same order `detect_runtime()` uses):

```bash
if [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "claude" ] || [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "codex" ]; then
  :
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "opencode" ]; then
  echo "Token Optimizer — OpenCode runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "copilot" ]; then
  echo "Token Optimizer — GitHub Copilot runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "cursor" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "antigravity" ]; then
  echo "Token Optimizer — Google Antigravity runtime detected."
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}${CLAUDE_PLUGIN_DATA:-}" ]; then
  :
elif [ -n "${OPENCODE_BIN:-}${OPENCODE_CONFIG_DIR:-}${OPENCODE_DATA_DIR:-}${OPENCODE_CONFIG:-}${OPENCODE_CLIENT:-}" ]; then
  echo "Token Optimizer — OpenCode runtime detected."
elif [ -n "${COPILOT_HOME:-}${TOKEN_OPTIMIZER_COPILOT_HOME:-}" ]; then
  echo "Token Optimizer — GitHub Copilot runtime detected."
elif [ -n "${TOKEN_OPTIMIZER_CURSOR_HOME:-}" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ -n "${CURSOR_PROJECT_DIR:-}" ] && [ -n "${CURSOR_VERSION:-}" ]; then
  echo "Token Optimizer — Cursor runtime detected."
elif [ -n "${TOKEN_OPTIMIZER_ANTIGRAVITY_HOME:-}" ]; then
  echo "Token Optimizer — Google Antigravity runtime detected."
fi
```

| It prints | Do this |
|-----------|---------|
| "OpenCode runtime detected." | Stop. Follow `references/opencode-workflow.md` (Token Optimizer runs as a native plugin there). |
| "Cursor runtime detected." | Stop. Follow `references/cursor-workflow.md` (it runs through the Cursor hook bridge). |
| "GitHub Copilot runtime detected." | Stop. Follow the Copilot guidance in `docs/copilot.md`. |
| "Google Antigravity runtime detected." | Stop. Follow `docs/antigravity.md`. |
| nothing | Continue to b. |

**b. Resolve `$MEASURE_PY` once.** Every later command uses it:

```bash
# Resolve measure.py to the NEWEST installed copy across channels so a stale
# plugin-cache copy never shadows a fresh install. find -L follows the
# install.sh symlink under ~/.claude/skills; cd -P resolves it before reading each
# copy's plugin.json for its version. find (not bare globs) never errors under zsh.
MEASURE_PY=""; _best_ver=""
while IFS= read -r _cand; do
  [ -f "$_cand" ] || continue
  _root="$(cd -P -- "$(dirname -- "$_cand")/../../.." 2>/dev/null && pwd)"
  _ver="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_root/.claude-plugin/plugin.json" 2>/dev/null | head -1)"
  [ -n "$_ver" ] || _ver="0.0.0"
  if [ -z "$_best_ver" ] || [ "$(printf '%s\n%s\n' "$_ver" "$_best_ver" | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -n1)" = "$_ver" ]; then
    _best_ver="$_ver"; MEASURE_PY="$_cand"
  fi
done <<EOF
$(find -L "$HOME/.claude/skills" "$HOME/.claude/plugins/cache" "$HOME/.claude/token-optimizer" "$HOME/.codex/skills" "$HOME/.codex/plugins/cache" "$HOME/.config/opencode/plugins" -type f -name measure.py -path '*token-optimizer*/scripts/measure.py' 2>/dev/null)
EOF
if [ -z "$MEASURE_PY" ]; then echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; fi
```

**c. The authoritative gate.** The environment check cannot see an OpenCode started without its variables; this one scans the process tree:

```bash
python3 "$MEASURE_PY" report 2>&1 | head -1
```

Any "... runtime detected." line means stop and follow that runtime's file from the table above. On Codex (`TOKEN_OPTIMIZER_RUNTIME=codex` or a Codex environment) follow `references/codex-workflow.md`. Claude Code continues below.

## The audit (Claude Code)

Work through these in order and tick each off; a skipped phase stays in the list as `skip: <reason>`.

```
- [ ] 0. Setup            references/phase0-setup.md
- [ ] 1. Parallel audit   references/agent-prompts.md
- [ ] 2. Synthesis        references/agent-prompts.md (Synthesis Agent)
- [ ] 3. Present, then wait for the user's decision   references/presentation-workflow.md
- [ ] 4. Implement the approved changes               references/implementation-playbook.md
- [ ] 5. Verify and report before/after               references/agent-prompts.md (Verification Agent)
```

**0. Setup.** Context window detection, pre-check, backup, the coordination folder (`COORD_PATH`), hook checks, daemon, smart compaction. Then, only when `python3 "$MEASURE_PY" keepwarm-consent-status` returns `should_ask: true`, follow `references/keepwarm-consent.md` exactly; it spends the user's money, so its wording and command order are fixed.

**1. Parallel audit.** Dispatch six agents in one message, each with `COORD_PATH` and its prompt from `references/agent-prompts.md`. They gather and count, so they run on the cheapest 

BLOCKgrade F · trust 52/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

declared (13 observation(s))

Network

UNDECLARED (7 observation(s))

Shell

declared (8 observation(s))

Dependencies

pinned

Secrets in source

found

Findings (25)

"raw_output": "GITHUB_TOKEN=ghp_ABCDEFghijklmnopqrstuvwxyz0123456789\nPATH=/usr/bin\n",

"must_preserve": ["ghp_ABCDEFghijklmnopqrstuvwxyz0123456789"],

"src/secrets_demo.py:8:0: C0103 Variable name doesn't conform: SECRET_TOKEN=ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789\n"

"must_preserve": ["ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789"],

"│   │   │   └── ghp_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789.txt\n"

"raw_output": "SLACK_TOKEN=xoxb-FAKE-TEST-FIXTURE-00000\nDEBUG=true\n",

"must_preserve": ["xoxb-FAKE-TEST-FIXTURE-00000"],

exec(compile(_source_bytes, str(_source_path), 'exec'), _source_namespace)

exec(compile(_source_bytes, str(_source_path), 'exec'), _source_namespace)

"exec(compile((root / 'devin_source.py').read_bytes(), 'devin_source.py', 'exec'), namespace)\n"

_EXEC_RULE = re.compile(r'(?i)exec(?:\((.*)\))?')

exec(compile(content,str(source),'exec'),module.__dict__)

"/.ssh/",

"/.aws/",

"/.gnupg/",

"id_rsa",

"id_ed25519",

'    __import__(name)\n',

__import__(pkg)

mod = __import__(pkg)

"( T=\"$(mktemp -d)\" && cd \"$T\" && curl -fsSL --max-time 30 -o m.json %s && "

import urllib.request

with urllib.request.urlopen(url, timeout=timeout) as resp:  # noqa: S310 - fixed https host

import urllib.request

class _NoRedirect(urllib.request.HTTPRedirectHandler):

Gates applied: critical_finding, no_behavioural_pass.

[![ModelsAtlas audit: Token Optimizer](https://modelsatlas.com/skills/alexgreensh/token-optimizer/badge.svg)](https://modelsatlas.com/skills/alexgreensh/token-optimizer/)

Not your listing, or something out of date? Claim or update your listing.