SkillAgentSearch skills...

token-optimizer

Audits a Claude Code or Codex setup for context-window waste, fixes it with the user's approval, and measures the saving

Install / Use

npx skills add alexgreensh/token-optimizer --skill token-optimizer

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

95/100

Supported Platforms

Claude Code
OpenAI Codex

Tags

Our assessment of token-optimizer

token-optimizer scores 95/100 on our quality scale, 405th of 4,700 Development & Engineering skills we index (top 9%).

Its SKILL.md is 14 KB long, well organised into 18 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.

With 2,885 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
15/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 11 days ago, so token-optimizer is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

token-optimizer compared with similar skills

All 4 of these similar skills score higher than token-optimizer; compare them before choosing.

SkillScoreStarsUpdatedFormat
token-optimizer (this skill)by alexgreensh952.9k11d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install token-optimizer?
Run npx skills add alexgreensh/token-optimizer --skill token-optimizer. The install tabs above show the steps for each supported agent.
Which AI agents does token-optimizer work with?
It is written for Claude Code and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
Is token-optimizer safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is token-optimizer still maintained?
The repository was last updated 11 days ago, so token-optimizer is actively maintained.

name: token-optimizer description: Audit a Claude Code or Codex setup for context-window waste, then fix it and measure the savings. Use when context feels tight. effort: high

Token Optimizer

Never recommend cutting our own tools. 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:

# 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 [ "${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
  :  # 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."
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
  • 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 "… Cursor runtime detected." → STOP. Do not resolve measure.py, do not run any phase below. Read references/cursor-workflow.md (bundled with this skill) and follow it. On Cursor, Token Optimizer runs through the Cursor hook bridge; the Claude audit must not run.
  • Prints "… Google Antigravity runtime detected." → STOP and follow docs/antigravity.md for the same reason: on Antigravity, Token Optimizer runs as a native plugin, not a Claude audit.
  • 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:

# 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

With $MEASURE_PY resolved, run the runtime gate as the first executed command. Its output is a hard stop, not a hint:

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.
  • 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 0.5: Keep-Warm Consent (first run only, Claude Code)

Keep-Warm is opt-in and pays off only for API-key-billed Claude Code sessions. Ask once:

python3 "$MEASURE_PY" keepwarm-consent-status   # JSON: {billing_mode, consent, should_ask}

If should_ask is false, skip this phase silently (subscription users are never asked; declined/enabled users keep their choice). If should_ask is true, first compute the user's own projection, then present the pitch:

python3 "$MEASURE_PY" keepwarm-backfill --json --no-fence   # read modes."probe-only".net_usd

Read net_usd under modes."probe-only". If it is a positive number, include it as the projection. If backfill errors, returns nothing, or net_usd <= 0, drop the dollar sentence entirely (do not invent a number) and use the no-data wording below.

Keep your prompt cache warm automatically? When a Claude Code session pauses past its 1h cache window and resumes, the whole prefix is re-written at up to 2x input. Keep-Warm pings the cache just before expiry (~0.1x of the prefix, max 2 pings per pause) so a resume stays warm. A history-replay projection from your own last 30 days nets ~$<net_usd>/30d at the conservative probe-only setting. A tripwire auto-disables it if pings ever stop paying for themselves, and you can turn it off any time. Enable it?

No-data wording (when backfill yields no positive projection): drop the projection sentence and say "Your savings depend on your own pause-and-resume pattern; the dashboard will show your number once pings have fired."

Then record the answer (do this exactly once). Record the yes/no FIRST, so an interrupted run never strands an "asked" marker with no recorded answer:

# yes:
python3 "$MEASURE_PY" keepwarm-enable
# no:
python3 "$MEASURE_PY" keepwarm-disable

keepwarm-enable and keepwarm-disable are terminal states, so they already satisfy should_ask. Only if the user defers or ignores the question (records neither) run the shown-marker so they are not re-asked next run:

python3 "$MEASURE_PY" keepwarm-consent-asked          # mark shown (sticky); use ONLY when no enable/disable was recorded

keepwarm-enable records consent and installs the scheduler (macOS); on other OSes the scheduler is pending, so it is watchdog-only. It refuses on subscription with an honest message. To confirm it is armed:

python3 "$MEASURE_PY" keepwarm-scheduler status      # JSON: installed/loaded state (macOS)
python3 "$MEASURE_PY" keepwarm-tick --dry-run        # JSON: what the next tick would decide

Phase 1: Quick Audit (Parallel Agents)

Read references/agent-prompts.md for all prompt templates.

Dispatch 6 agents in parallel:

| Agent | Output File | Model | Task | |-------|-------------|-------|------| | CLAUDE.md Auditor | audit/claudemd.md | sonnet | Size, duplication, tiered content, cache structure | | MEMORY.md Auditor | audit/memorymd.md | sonnet | Size, overlap with CLAUDE.md | | Skills Auditor | audit/skills.md | sonnet | Count, frontmatter overhead, duplicates | | MCP Auditor | audit/mcp.md | sonnet | Deferred tools, broken/unused servers | | Commands Auditor | audit/commands.md | haiku | Count, menu overhead | | Settings & Advanced | audit/advanced.md | sonnet | Hooks, rules, settings, @imports, caching |

Pass COORD_PATH to each. Wait for all to complete. If any output file is missing, note the gap and proceed.


Phase 2: Analysis

Read the Synthesis Agent prompt from references/agent-prompts.md. Dispatch with model="opus" (fallback: sonnet). It reads all audit files and writes {COORD_PATH}/analysis/optimization-plan.md. If missing, present raw audit files instead.


Phase 3: Present Findings

Read references/presentation-workflow.md for the findings template, dashboard generation, and URL presentation logic. Generate the dashboard:

python3 $MEASURE_PY dashboard --coord-path $COORD_PATH

Wait for user decision before proceeding.


Phase 4: Implementation

Read references/implementation-playbook.md for detailed steps. Available actions: 4A-4P covering CLAUDE.md, MEMORY.md, Skills, File Exclusion, MCP, Hooks, Cache, Rules, Settings, Descriptions, Compact Instructions, Model Routing, Smart Compaction, Quality Check, Version-Aware Optimizations, and Smart Routing. Templates in examples/. Always backup before changes. Present diffs for approval.


Phase 5: Verification

Read the Verification Agent prompt from references/agent-prompts.md. Dispatch with model="haiku". Re-measures everything and calculates savings. Present before/after comparison and behavioral next steps.


Session Continuity: Cold-Resume-Lean

Reopen a f

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.9k
CategoryDevelopment
Updated11d ago
Forks225

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium