Help us improve
Share bugs, ideas, or general feedback.
From token-optimizer
Analyzes context window usage and session habits to provide token efficiency coaching for Claude Code/Codex. Use when building new projects, diagnosing sluggish sessions, or designing multi-agent systems.
npx claudepluginhub alexgreensh/token-optimizer --plugin token-optimizerHow this skill is triggered — by the user, by Claude, or both
Slash command
/token-optimizer:token-coachThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Interactive coaching for Claude Code or Codex architecture decisions. Analyzes your setup, identifies patterns (good and bad), and gives personalized advice with real numbers.
Audits Claude Code or Codex setup to identify context window waste, implements fixes via config cleanup and autocompact management, and measures token savings.
Tracks tokens, analyzes caching behavior, identifies bottlenecks in tool usage, and estimates costs to optimize Claude Code session performance and efficiency.
Analyzes Claude Code conversation logs for token usage, costs, cache hit rates, workflow patterns (skills, agents, hooks), and cost optimizations. Generates interactive HTML dashboard.
Share bugs, ideas, or general feedback.
Interactive coaching for Claude Code or Codex architecture decisions. Analyzes your setup, identifies patterns (good and bad), and gives personalized advice with real numbers.
Use when: Building something new, existing setup feels slow, designing multi-agent systems, or want a quick health check.
RUNTIME="${TOKEN_OPTIMIZER_RUNTIME:-}"
if [ -z "$RUNTIME" ]; then
if [ -n "$CLAUDE_PLUGIN_ROOT" ] || [ -n "$CLAUDE_PLUGIN_DATA" ]; then
RUNTIME="claude"
elif [ -n "$CODEX_HOME" ] || [ -d "$HOME/.codex" ]; then
RUNTIME="codex"
else
RUNTIME="claude"
fi
fi
MEASURE_PY=""
for f in "$HOME/.codex/skills/token-optimizer/scripts/measure.py" \
"$HOME/.codex/plugins/cache"/*/token-optimizer/*/skills/token-optimizer/scripts/measure.py \
"$HOME/.claude/skills/token-optimizer/scripts/measure.py" \
"$HOME/.claude/plugins/cache"/*/token-optimizer/*/skills/token-optimizer/scripts/measure.py \
"$PWD/skills/token-optimizer/scripts/measure.py"; do
[ -f "$f" ] && MEASURE_PY="$f" && break
done
[ -z "$MEASURE_PY" ] || [ ! -f "$MEASURE_PY" ] && { echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; }
export TOKEN_OPTIMIZER_RUNTIME="$RUNTIME"
python3 "$MEASURE_PY" coach --json
Parse the JSON output. This gives you: snapshot (current measurements), detected patterns, coaching questions, focus suggestions, and history (trend data from past sessions).
The history key contains (when trends.db has enough data):
quality_recent_avg / quality_prior_avg - 7-day vs older quality scoresduration_recent_avg / duration_prior_avg - session length trends (minutes)cache_hit_recent_avg / cache_hit_prior_avg - prompt cache hit rate trendsgrade_d_pct_recent / grade_distribution - recent grade breakdowntotal_cost_usd / cost_per_session_usd / sessions_in_period - spend summaryquality_short_sessions / quality_long_sessions / optimal_session_hint - duration-quality correlationcompression_measured_saved / compression_opportunity_tokens - compression gapmulti_model_session_pct - percentage of recent sessions that switched models mid-sessionHistorical patterns also appear in the patterns_bad array (e.g. "Quality Declining", "Session Duration Creep", "Cache Hit Rate Dropping", "Cache Hit Rate Dropping (Model Switches)", "Frequent Model Switching", "High Cost Per Session", "Compression Opportunity Gap").
python3 "$MEASURE_PY" quality current --json 2>/dev/null
If available, parse the quality score and issues. This enriches coaching with session-level insights (not just setup overhead). If the command fails (pre-v2.0 install), skip gracefully.
if [ "$RUNTIME" = "codex" ]; then
python3 "$MEASURE_PY" codex-doctor --project "$PWD" --json 2>/dev/null
fi
Use this to tell the user whether balanced hooks, compact prompt guidance, dashboard refresh, and status-line support are installed.
python3 "$MEASURE_PY" keepwarm-consent-status # JSON: {billing_mode, consent, should_ask}
If should_ask is false, skip silently. If true (API-billed, not yet asked), offer Keep-Warm once after the coaching conversation. First compute the projection from the user's own history:
python3 "$MEASURE_PY" keepwarm-backfill --json --no-fence # read modes."probe-only".net_usd
Then pitch: when a session pauses past its 1h cache window and resumes, the prefix is re-written at up to 2x; Keep-Warm pings before expiry (~0.1x, max 2 pings/pause) so resumes stay warm, with a tripwire that auto-disables if it stops paying off. If modes."probe-only".net_usd is positive, say "a history-replay projection from your own last 30 days nets ~$<net_usd>/30d at probe-only"; if backfill yields nothing or net_usd <= 0, drop the dollar sentence (do not invent one) and say savings depend on their own pattern and the dashboard shows it once pings fire.
Record the answer — yes/no FIRST so an interrupted run never strands an "asked" marker with no answer: keepwarm-enable (yes) or keepwarm-disable (no), both terminal. Only if the user defers/ignores (records neither) run keepwarm-consent-asked as the shown-marker. keepwarm-enable records consent and installs the scheduler (macOS); other OSes are scheduler-pending, watchdog-only. Confirm it is armed with keepwarm-scheduler status and keepwarm-tick --dry-run. It is off by default and refuses on subscription auth.
Ask ONE question:
What's your goal today? a) Building something new, want it token-efficient from the start b) Existing project feels sluggish / context fills too fast c) Designing a multi-agent system, want architecture advice d) Quick health check with actionable tips
Wait for the answer. Don't dump info before they choose.
Resolve the token-coach skill directory:
COACH_DIR=""
if [ -d "$HOME/.codex/skills/token-coach" ]; then
COACH_DIR="$HOME/.codex/skills/token-coach"
elif [ -d "$HOME/.codex/skills/token-optimizer/../token-coach" ]; then
COACH_DIR="$HOME/.codex/skills/token-optimizer/../token-coach"
elif [ -d "$HOME/.claude/skills/token-coach" ]; then
COACH_DIR="$HOME/.claude/skills/token-coach"
elif [ -d "$HOME/.claude/skills/token-optimizer/../token-coach" ]; then
COACH_DIR="$HOME/.claude/skills/token-optimizer/../token-coach"
else
COACH_DIR="$(find "$HOME/.codex/plugins/cache" "$HOME/.claude/plugins/cache" -path "*/token-coach" -type d 2>/dev/null | head -1)"
fi
Load references based on intake choice:
$COACH_DIR/references/coach-patterns.md + $COACH_DIR/references/quick-reference.md$COACH_DIR/references/agentic-systems.md + $COACH_DIR/references/quick-reference.md$COACH_DIR/references/quick-reference.md only (fast path)Read the matching example from $COACH_DIR/examples/ as a few-shot template:
coaching-session-new-project.mdcoaching-session-heavy-setup.mdcoaching-session-agentic.mdRead $COACH_DIR/references/coaching-scripts.md for conversation structure.
This is a CONVERSATION. Not a wall of text.
history data is available, weave in trend insights naturally:
For Codex specifically, translate all advice to native Codex concepts:
AGENTS.md instead of CLAUDE.mdMEMORY.mdTone: Knowledgeable friend, not corporate consultant. Be direct about what matters and why. Use real numbers from their data.
Anti-patterns to call out: Reference the anti-patterns from coach-patterns.md. Name them ("You've got the 50-Skill Trap going on").
Continue the conversation for 2-4 exchanges. Let the user ask questions. Adjust advice based on what they tell you about their workflow.
After the conversation, generate a prioritized action plan:
python3 $MEASURE_PY setup-smart-compact)TOKEN_OPTIMIZER_RUNTIME=codex python3 $MEASURE_PY codex-install --project .)/compact or /clear before continuing/token-optimizer for the full audit + implementation if they want to go beyond coachingFormat: Keep it scannable. Numbered list with bold action names, one-line description, estimated savings.
If measure.py generated a coach dashboard tab, mention it:
"Your Token Health Score and pattern analysis are in the dashboard. Run python3 $MEASURE_PY dashboard to see it."
For Codex, also give the generated file location: ~/.codex/_backups/token-optimizer/dashboard.html.