token-coach

# Token Coach: Plan Token-Efficient Before You Build

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.

---

## Phase 0: Initialize

1. **Resolve runtime and measure.py path** (same as token-optimizer):
```bash
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"
```

2. **Collect coaching data**:
```bash
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 scores
- `duration_recent_avg` / `duration_prior_avg` - session length trends (minutes)
- `cache_hit_recent_avg` / `cache_hit_prior_avg` - prompt cache hit rate trends
- `grade_d_pct_recent` / `grade_distribution` - recent grade breakdown
- `total_cost_usd` / `cost_per_session_usd` / `sessions_in_period` - spend summary
- `quality_short_sessions` / `quality_long_sessions` / `optimal_session_hint` - duration-quality correlation
- `compression_measured_saved` / `compression_opportunity_tokens` - compression gap
- `multi_model_session_pct` - percentage of recent sessions that switched models mid-session

Historical 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").

3. **Check context quality** (v2.0):
```bash
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.

4. **For Codex, check setup readiness**:
```bash
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.

5. **Keep-Warm consent (first run only, Claude Code)**:
```bash
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:
```bash
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.

## Phase 1: Intake

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.

## Phase 2: Load Context (based on intake)

Resolve the token-coach skill directory:
```bash
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:
- **Option a or b**: Read `$COACH_DIR/references/coach-patterns.md` + `$CO