token-coach

トークンコーチ

ユーザーのマシンで測定した数値をもとに、トークンがどこで消費され、何を変更すべきかを話し合うコーチングの会話です。最終的に、ユーザーが納得した、優先順位付きの短いアクションプランを作成します。セットアップを編集する完全な監査が必要な場合は、token-optimizer に引き継いでください。

Token Optimizer 独自のスキル（token-optimizer、token-coach、token-dashboard、fleet-auditor、resume-checkpoint）は測定レイヤーです。実行頻度にかかわらず、未使用スキル、アーカイブ、統合に関する提案からは除外してください。

1. データを収集する

まず、必ずこれを実行してください。最新のインストール済みコピーを見つけるため、古いプラグインキャッシュが応答することはありません。

RUNTIME="${TOKEN_OPTIMIZER_RUNTIME:-}"
if [ -z "$RUNTIME" ]; then
  if [ -n "$CLAUDE_PLUGIN_ROOT" ] || [ -n "$CLAUDE_PLUGIN_DATA" ]; then
    RUNTIME="claude"
  elif [ -n "$OPENCODE" ] || [ -n "$OPENCODE_BIN" ] || [ -n "$OPENCODE_CONFIG_DIR" ] || [ -n "$OPENCODE_CONFIG" ]; then
    RUNTIME="opencode"
  elif [ -n "$CODEX_HOME" ]; then
    RUNTIME="codex"
  # Explicit config-dir env of another harness: same tier as Python's
  # detect_runtime() (above CLAUDECODE, which every Claude Code child inherits).
  elif [ -n "$HERMES_HOME" ]; then
    RUNTIME="hermes"
  elif [ -n "$COPILOT_HOME" ] || [ -n "$TOKEN_OPTIMIZER_COPILOT_HOME" ]; then
    RUNTIME="copilot"
  elif [ -n "$TOKEN_OPTIMIZER_CURSOR_HOME" ]; then
    RUNTIME="cursor"
  elif [ -n "$TOKEN_OPTIMIZER_ANTIGRAVITY_HOME" ]; then
    RUNTIME="antigravity"
  elif [ -n "$GROK_HOME" ] || [ -n "$TOKEN_OPTIMIZER_GROK_HOME" ]; then
    RUNTIME="grok"
  elif [ -n "$CLAUDECODE" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ] || [ -n "$CLAUDE_CODE_SESSION_ID" ]; then
    RUNTIME="claude"
  elif [ -d "$HOME/.config/opencode" ] && [ ! -d "$HOME/.codex" ]; then
    RUNTIME="opencode"
  elif [ -d "$HOME/.codex" ]; then
    RUNTIME="codex"
  else
    RUNTIME="claude"
  fi
fi

# 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/cache" "$HOME/.config/opencode/plugins" -type f -name measure.py -path '*token-optimizer*/scripts/measure.py' 2>/dev/null)
EOF
if [ -z "$MEASURE_PY" ] || [ ! -f "$MEASURE_PY" ]; then echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; fi
export TOKEN_OPTIMIZER_RUNTIME="$RUNTIME"
# The coach files ship beside measure.py, so they are always the same version.
COACH_DIR="$(cd -P -- "$(dirname -- "$MEASURE_PY")/../../token-coach" 2>/dev/null && pwd)"
[ -d "$COACH_DIR/references" ] || echo "[Error] token-coach references not found beside $MEASURE_PY. Reinstall Token Optimizer."

次に、失敗したコマンドはスキップして、以下を収集してください（古いインストールには一部がありません）。

python3 "$MEASURE_PY" coach --json                      # snapshot, patterns, history, questions
python3 "$MEASURE_PY" quality current --json            # this session's quality score and issues
python3 "$MEASURE_PY" subagent-cache status --json      # Claude Code: subagent cache lifetime and its payoff
python3 "$MEASURE_PY" compact-advice --json             # Claude Code: would an earlier compact window pay off
python3 "$MEASURE_PY" recommendations --json            # Claude Code: the daily usage-recommendations record
[ "$RUNTIME" = "codex" ] && python3 "$MEASURE_PY" codex-doctor --project "$PWD" --json

コーチ用 JSON に含まれる内容：snapshot（現在のオーバーヘッド）、patterns_good と patterns_bad（詳細と修正方法を含む、名前付きのパターン）、history（直近7日間とそれ以前の比較：品質、セッション時間、キャッシュヒット率、評価の分布、セッションあたりのコスト、短時間セッションと長時間セッションの比較、圧縮の差、モデルを切り替えたセッションの割合）、存在する場合の deterministic_candidates（ユーザーが繰り返し行っており、スクリプトで実行できる作業）、および Claude Code の usage_recommendations（日次測定記録：コンパクトウィンドウとサブエージェントのキャッシュ有効期間についてそれぞれ1項目ずつ含み、ユーザーが以前の推奨事項に対応して数値が変化した場合は wins も含みます）。各フィールドの意味と引用する数値については、references/quick-reference.md を参照してください。

引用する数値はすべて、これらの出力またはクイックリファレンスから取得してください。データが少ない場合やコマンドが何も返さなかった場合は、その旨を伝え、ユーザーから聞いた内容をもとにコーチングしてください。数値を捏造すると、実際の数値に対するユーザーの信頼も損なわれます。

2. ユーザーの希望を尋ねる

調査結果を示す前に質問を1つして、回答を待ってください。

今日の目標は何ですか？ a) 新しいものを作り始めるので、最初からトークン効率を高めたい b) 既存のセットアップが遅く感じる、またはコンテキストがすぐにいっぱいになる c) マルチエージェントシステムを設計する d) 簡単なヘルスチェック e) ワークフローや自動化を見直す：モデルが本当に必要な手順はどれか

依頼内容ですでに答えがわかる場合は、質問を省略してください。

3. 目標に必要な資料を読む

目標	読む資料	参考にする例
a、b	references/coach-patterns.md、クイックリファレンス	examples/coaching-session-new-project.md（a）、examples/coaching-session-heavy-setup.md（b）
c	references/agentic-systems.md、クイックリファレンス	examples/coaching-session-agentic.md
d	クイックリファレンスのみ	なし。手早く済ませてください
e	references/deterministic-stages.md	なし

a、b、c の場合は、会話の進め方について references/coaching-scripts.md も読んでください。すべてのパスは $COACH_DIR の下にあります。例は口調と進行のペースを示すものであり、内容はユーザーのデータに基づいて決めてください。

4. コーチ

これは会話です。最初に1つか2つの所見を伝えてから質問し、以降はユーザーに進め方を決めてもらいます。

• 最も深刻な問題から始めます。 セッション品質スコアが70未満なら、まずその問題を取り上げます（「品質は100点中58点で、古いツール結果が40Kトークンを占めています」）。そうでなければ、横ばいの数値より悪化傾向を優先します。品質の低下、セッションの長期化、キャッシュヒット率の低下などです。
• ユーザーの数値を使い、パターンに名前を付けます。 「47個のスキルは開始のたびに約4,700トークンを消費する、『50スキルの落とし穴』です」は伝わりますが、「スキルはトークンを消費します」では伝わりません。
• 仕組みを一文で説明します。 そうすれば、このスキルに列挙されていないケースにもアドバイスが活かせます。例：セッション途中でモデルを切り替えるとプロンプトキャッシュが破棄されるため、モデルは最初に選びます。サブエージェント内でより安価なモデルを使うのは問題ありません。独自のコンテキストを持つためです。
• サブエージェントのキャッシュ。 サブエージェントには、サブスクリプション利用時も5分間のキャッシュがあります。Token Optimizer は、このユーザーのトランスクリプトで1時間の利用が元を取れるかを測定して推奨します（キーの設定は行いません）。subagent-cache status の測定結果と advice: の行を報告します。このユーザーのパターンでは効果がマイナスの場合も同様です。同じ判定は、ダッシュボードの「利用状況に基づく提案」セクションが参照する、日次の usage_recommendations レコードにも記録されます。
• 圧縮のタイミング。 compact-advice は、コストと品質を並べて示す、ユーザー自身の履歴に基づく推定として提示し、出力されたコマンドも伝えます。早めに圧縮すると、その後の各ターンでキャッシュ読み取りトークンを節約できますが、初期の指示が失われるリスクもあるため、判断はユーザーに委ねます。要約された recommend／keep 判定も、日次の usage_recommendations レコードに記録されます。
• 利用状況に基づく提案。 usage_recommendations に recommend 項目がある場合は、まずそれを伝えます。十分なデータがあることを確認したうえで導き出された、本日の測定結果です。wins が空でない場合は、「変更してから」の測定された変化として、両方の数値を挙げます。その変更が原因だとは断定しません。
• 目標e、または deterministic_candidates が空でない場合： ワークフローを段階ごとに確認し、各段階を「入力で出力が決まるため、通常のコードで処理」と「判断が必要なため、モデルで処理」に分類します。決定論的な段階に関するリファレンスに従ってください。
• Codex ユーザーには Codex 用語だけを使います。 AGENTS.md、Codex のメモリ、Codex のバランス型フック、推論の強さとモデル選択、コンパクトなプロンプトのガイダンスを使います。Claude のモデル名や CLAUDE.md は意味を持ちません。

知識豊富な友人のように話します。通常は2〜4回のやり取りを想定し、決まった台本よりもユーザーの質問に沿って進めます。

5. 実行計画に合意する

最後に、影響の大きい順に3〜5個のアクションを提示します。それぞれに、太字の名前、実行内容を示す一文、節約の推定値とその根拠、そして手軽に実行できる改善か、より大がかりな変更かを含めます。該当する場合は、次の内容も含めます。

• Claude Code で品質が70未満の場合：python3 "$MEASURE_PY" setup-smart-compact。Codex の場合：TOKEN_OPTIMIZER_RUNTIME=codex python3 "$MEASURE_PY" codex-install --project .
• 品質が50未満の場合：作業を続ける前に /compact または /clear を実行します。
• モデルからスクリプトに移行する手順。フック、スクリプト、スケジュールされたジョブのいずれを使うか、その仕組みも記載します。

次に、計画とデータが一致しているか確認します。すべての数値はコマンド出力またはクイックリファレンスに基づいていること、また、Token Optimizer 自身のスキルに影響するアクションがないことを確かめます。問題があれば修正し、送信前にもう一度確認します。

変更を代わりに実行してほしい場合は /token-optimizer を案内します。傾向を確認したい場合は、ダッシュボード（python3 "$MEASURE_PY" dashboard。Codex では記憶しているパスを決して使わず、出力された Dashboard: の行を伝えます）を案内します。

Keep-Warm（Claude Code、質問は一度だけ）

計画の提示後、python3 "$MEASURE_PY" keepwarm-consent-status を実行します。should_ask が true の場合に限り、references/keepwarm-consent.md の指示に厳密に従います。ユーザーのお金を使うため、文言とコマンドの順序は固定されています。

Claude Opus 5.5 と Sonnet 5.5、および Codex 上の GPT-5.6 向けに作成し、動作確認済みです。