token-optimizer

# Token Optimizer

> **Never recommend cutting our own tools (issue #111).** In every recommendation you produce, NEVER suggest removing, archiving, trimming, disabling, or consolidating Token Optimizer's own skills — `token-optimizer`, `token-coach`, `token-dashboard`, `fleet-auditor`. They are the measurement layer; recommending the user delete them to "save ~200 tokens" is self-cannibalizing. Exclude them from every unused-skill / archive / consolidation suggestion, regardless of invocation history.

Audits a Claude Code or Codex setup, identifies context window waste, implements fixes, and measures savings.

**Target**: 5-15% context recovery through config cleanup, up to 25%+ with autocompact management.

---

## Step 0: Resolve measure.py, then gate on runtime (run this first)

> **Runtime pre-gate (environment only — touches no `~/.claude` path).** Before resolving any script
> path, check the environment directly. This keeps non-Claude runtimes from ever resolving a
> `~/.claude` path (issue #57):
> ```bash
> # OpenCode / Copilot set these; detect them WITHOUT touching ~/.claude.
> # Explicit TOKEN_OPTIMIZER_RUNTIME is authoritative and checked first (matches detect_runtime()).
> # An explicit override to a Claude/Codex runtime is authoritative (matches detect_runtime); proceed.
> # Claude plugin env vars (CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA) are checked BEFORE
> # OPENCODE_* env signals so a genuine Claude session with a stray OPENCODE_* export
> # is NOT stopped here — it falls through to measure.py, which resolves correctly
> # (detect_runtime step 3 beats step 4). This mirrors the Python priority order.
> if [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "claude" ] || [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "codex" ]; then
>   :  # fall through to the measure.py resolver + authoritative gate below
> 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 [ -n "${CLAUDE_PLUGIN_ROOT:-}${CLAUDE_PLUGIN_DATA:-}" ]; then
>   :  # genuine Claude Code session; fall through to measure.py (step 3 beats step 4)
> 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."
> fi
> ```
> - Prints **"… OpenCode runtime detected."** → **STOP. Do not resolve `measure.py`, do not run any
>   phase below.** Read `references/opencode-workflow.md` (bundled with this skill) and follow it.
>   On OpenCode, Token Optimizer runs as a native plugin; the Claude audit must not run.
> - Prints **"… GitHub Copilot runtime detected."** → **STOP** and follow the Copilot guidance for the
>   same reason.
> - Prints nothing → continue to resolve `$MEASURE_PY` below. This env-only pre-gate does NOT
>   check the process tree, so OpenCode launched without exporting `OPENCODE_*` env vars (e.g. a
>   bare `opencode` binary or `node /path/to/opencode`) prints nothing here. The
>   `measure.py report` runtime gate that follows is the **authoritative** second check — it runs
>   `detect_runtime()` which includes the ancestor-process scan and will catch those cases.

Resolve the script path **once, before any phase or runtime decision**. Every
command below — including the runtime gate — depends on `$MEASURE_PY`, so it
must be set first:
```bash
# Resolve measure.py to the NEWEST installed copy across channels so a stale
# plugin-cache copy never shadows a fresh install (issue #57). 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
```

With `$MEASURE_PY` resolved, run the runtime gate as the **first executed
command**. Its output is a hard stop, not a hint:
```bash
python3 "$MEASURE_PY" report 2>&1 | head -1
```

- Prints **"Token Optimizer — OpenCode runtime detected."** → **STOP. Run none
  of the phases below.** Read `references/opencode-workflow.md` and follow it.
  The Claude Code phases scan and mutate `~/.claude`, which is the wrong target
  when the user is in OpenCode (issue #57).
- Prints any other **"… runtime detected."** notice (for example GitHub
  Copilot) → STOP and follow that runtime's guidance, for the same reason.
- Otherwise continue: if `TOKEN_OPTIMIZER_RUNTIME=codex` or a Codex environment
  is detected, read `references/codex-workflow.md` and follow its chat-first
  workflow instead of the phases below. Genuine Claude Code proceeds to Phase 0.

---

## Phase 0: Initialize (Claude Code)

`MEASURE_PY` was already resolved in Step 0 — do **not** re-resolve it.

Read `references/phase0-setup.md` for the full setup sequence: context window detection, pre-check, backup, coordination folder, hook checks, daemon setup, and smart compaction.

---

## Phase