/token-optimizer

name: token-optimizer
description: Route broad repository discovery to a cheaper worker model using each client's native subagents, keeping the main agent for decisions and targeted verification. Use when asked to "reduce token usage", "delegate bulk reading", "set up a cheap reader agent", or "why is my context filling up".
argument-hint: "[inspect|setup|doctor|explain|benchmark|report|disable|remove]"
title: "Token Optimizer Command"
sidebar_label: "token-optimizer"
custom_edit_url: null

Route broad repository discovery to a cheaper worker model using each client's native subagent mechanism. Keep the main agent for decisions and targeted verification.

Read `references/token-optimizer.md` before responding.

---

Interactive Wizard (fires when no arguments are provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. inspect   — detect client, versions, existing agents and hooks, conflicts
  2. setup     — choose scope, worker model, routing mode; write a reviewable diff
  3. doctor    — check delegation, model, redirection, and read limit separately
  4. explain   — dry-run one path or payload: show the rule and proposed decision
  5. benchmark — run a fixture suite in isolated runs and compare
  6. report    — show measured usage and clearly labelled estimates
  7. disable   — turn the optimizer off (enabled: false)
  8. remove    — remove owned, unmodified assets

Enter 1-8 or mode name:

**Q2 — Context** (after mode selected, one at a time):

• **setup**: `Which client? (claude / copilot-cli / vscode)` then `Worker model? (claude-haiku-4.5 / gpt-5-mini / gpt-5.4-mini)` then `Routing mode? (audit / redirect — audit recommended for a first install)`
• **explain**: `Give me a file path, or a JSON payload to classify:`
• **benchmark**: `Which fixture suite?` then offer `all` plus every family from `jq -r '[.tasks[].family] | unique | .[]' evals/token-optimizer/manifest.json`
• **report**: no question — reads the log path from the config's `log:` key
• **disable** / **remove**: `Which client's configuration?`

For `setup` on `copilot-cli`, do not offer `redirect`. It is unsupported and the core caps it to audit. Say so rather than accepting the choice and silently downgrading it.

Then proceed into the relevant mode below.

---

Mode: inspect

Read-only environment scan: detect client, versions, existing agents and hooks, coexistence notes.

Steps:

1. Detect which client is present and report versions:

   # Try each in order
   claude --version 2>/dev/null || echo "claude: not installed"
   copilot --version 2>/dev/null || echo "copilot: not installed"
   code --version 2>/dev/null | head -n1 || echo "vscode: not installed"

2. Check for existing agent definitions in all locations where clients read them:

• `.github/agents/` — repository-scoped agents, shared by Copilot CLI and VS Code
• `~/.copilot/agents/` — user-scoped Copilot CLI agents
• `.claude/agents/` and `~/.claude/agents/` — repository- and user-scoped Claude Code agents

List any agent whose name contains `reader`, `bulk`, `worker`, or matches the default `platform-bulk-reader`. Report the agent names found; do not attribute agents in `.github/agents/` to one client from the path alone.

3. Check for existing hooks across **all three** Copilot surfaces (not just one):

• `.github/hooks/*.json` (repository scope, project-managed)
• `settings.json` `hooks` key in the repository root (repository scope, alternative location)
• `~/.copilot/config.json` `hooks` key (user scope, global)

For Claude Code, check `.claude/settings.json` for matcher groups on `PreToolUse` events.

Report any hook whose command string contains `optimize.sh` or `token-optimizer`.

4. Check whether an `ai-governance` hook is registered on the same event. This is a coexistence note, not a conflict — the two compose: `ai-governance` governs write intent, `token-optimizer` routes reads. Report it as:

   Note: ai-governance hook registered on PreToolUse — the two compose (governance
         blocks or logs violations, optimizer delegates reads).

5. Report the ten largest tracked files, so the operator knows what would be delegated:

   git ls-files | xargs wc -l 2>/dev/null | sort -rn | head -n 10

6. Check for existing `.token-optimizer.yaml` and `.token-optimizer/` directory. Report current `enabled` and `mode` settings if a config exists.

7. Check for `yq` and `jq` presence:

   command -v yq >/dev/null 2>&1 && echo "yq: installed" || echo "yq: not installed"
   command -v jq >/dev/null 2>&1 && echo "jq: installed" || echo "jq: not installed"

**Validation:** Print a summary table:

client:       <detected>
version:      <version>
agents found: <count> (<names>)
hooks found:  <count> (<event names>)
config:       present|absent
yq/jq:        both|yq only|jq only|neither

Mode: setup

Install the optimizer: copy assets, write config, register hooks, add ownership markers. The optimizer installs per repository because its config, state directory and hook command are all resolved relative to the repository root.

Steps:

1. Confirm the target client from the wizard answer (claude / copilot-cli / vscode).

2. All assets install to the repository scope: `.token-optimizer/`, `.token-optimizer.yaml`, `.claude/settings.json` or `.github/hooks/`. The optimizer's config and hook are repository-scoped. Agent templates can be installed at user scope (`~/.claude/agents/`, `~/.copilot/agents/`), but the core and its config remain repository-relative.

3. Confirm the worker model. Verified valid on Copilot CLI 1.0.59: `claude-haiku-4.5`, `gpt-5-mini`, `gpt-5.4-mini`. On Claude Code use `haiku` or a concrete model id your provider exposes. Only the VS Code coordinator pins a model (`claude-sonnet-4.6`); the Copilot CLI coordinator sets none and inherits the session's, and Claude Code ships no coordina