token-optimizer

Token Optimizer

セットアップがコンテキストウィンドウをどこで消費しているかを測定し、改善策を提示し、ユーザーが承認したものを適用して、再測定します。成果物は、ユーザーが検証できる変更前と変更後の結果であり、すべての変更はバックアップされています。一般的には、設定の整理によってウィンドウの5～15%を回復できます。圧縮とキャッシュの設定がユーザーの作業方法に合っていない場合は、さらに多く回復できることがあります。

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

ステップ 0：このランタイムに適したワークフローを選ぶ

以下の監査では ~/.claude を読み取り、編集します。これは Claude Code 以外では対象として不適切なため、パスに触れる前にランタイムを確定してください。次のコマンドを、記載の順序どおりに実行してください。

a. 環境チェック（ファイルには触れません。明示的に設定された TOKEN_OPTIMIZER_RUNTIME が優先され、Claude のプラグイン変数は、detect_runtime() と同じ順序で、予期せず設定された OPENCODE_* 環境変数より先にチェックされます）：

if [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "claude" ] || [ "${TOKEN_OPTIMIZER_RUNTIME:-}" = "codex" ]; then
  :
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
  :
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

表示される内容	実行すること
"OpenCode runtime detected."	停止してください。references/opencode-workflow.md に従ってください（Token Optimizer はそこでネイティブプラグインとして実行されます）。
"Cursor runtime detected."	停止してください。references/cursor-workflow.md に従ってください（Cursor フックブリッジ経由で実行されます）。
"GitHub Copilot runtime detected."	停止してください。docs/copilot.md の Copilot 向けガイダンスに従ってください。
"Google Antigravity runtime detected."	停止してください。docs/antigravity.md に従ってください。
何も表示されない	b に進んでください。

b. $MEASURE_PY を一度だけ解決します。 以降のすべてのコマンドでこれを使用します：

# 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

c. 権威ある判定ゲート。 環境チェックでは、環境変数なしで起動した OpenCode を検出できません。このチェックではプロセスツリーをスキャンします：

python3 "$MEASURE_PY" report 2>&1 | head -1

「... runtime detected.」と表示された場合は、停止して上の表に記載された、そのランタイム用のファイルに従ってください。Codex（TOKEN_OPTIMIZER_RUNTIME=codex または Codex 環境）の場合は、references/codex-workflow.md に従ってください。Claude Code の場合は、以下に進んでください。

監査（Claude Code）

以下を順番に進め、それぞれ完了したらチェックを付けます。フェーズをスキップした場合もリストに残し、skip: <reason> と記載します。

- [ ] 0. Setup            references/phase0-setup.md
- [ ] 1. Parallel audit   references/agent-prompts.md
- [ ] 2. Synthesis        references/agent-prompts.md (Synthesis Agent)
- [ ] 3. Present, then wait for the user's decision   references/presentation-workflow.md
- [ ] 4. Implement the approved changes               references/implementation-playbook.md
- [ ] 5. Verify and report before/after               references/agent-prompts.md (Verification Agent)

0. セットアップ。 コンテキストウィンドウの検出、事前チェック、バックアップ、調整用フォルダー（COORD_PATH）、フックのチェック、デーモン、スマートなコンパクションを行います。その後、python3 "$MEASURE_PY" keepwarm-consent-status が should_ask: true を返した場合に限り、references/keepwarm-consent.md の内容に厳密に従います。これはユーザーのお金を使うため、文言とコマンドの順序は固定されています。

1. 並列監査。 1 回のメッセージで 6 つのエージェントを起動し、それぞれに COORD_PATH と references/agent-prompts.md に記載されたプロンプトを渡します。情報の収集と集計を行うため、実行には対応可能なモデルのうち最も低コストのものを使います。判断が必要になるのは統合の段階です。

エージェント	書き込み先	調査対象
CLAUDE.md	audit/claudemd.md	サイズ、重複、階層化、キャッシュ構造
MEMORY.md	audit/memorymd.md	サイズ、CLAUDE.md との重複
スキル	audit/skills.md	数、フロントマターのオーバーヘッド、重複
MCP	audit/mcp.md	遅延読み込みのツール、壊れているサーバーまたは未使用のサーバー
コマンド	audit/commands.md	数、メニューのオーバーヘッド
設定と詳細項目	audit/advanced.md	フック、ルール、設定、@インポート、キャッシュの有効期間、コンパクションウィンドウ

出力ファイルがない場合は、作業を中断する理由ではなく、報告すべき不足事項として扱います。 2. 統合。 利用可能な最も高性能なモデルを使うエージェント 1 つがすべての監査ファイルを読み込み、{COORD_PATH}/analysis/optimization-plan.md に書き込みます。失敗した場合は、監査ファイルをそのまま提示します。

3. 提示。 ダッシュボードを生成し、プレゼンテーションのワークフローに従って調査結果を提示してから、待機します。

python3 "$MEASURE_PY" dashboard --coord-path "$COORD_PATH"

4. 実装。 ユーザーが承認した内容のみを、プレイブック（アクション 4A-4P：CLAUDE.md、MEMORY.md、スキル、ファイルの除外、MCP、フック、キャッシュ、ルール、設定、説明、コンパクト化の指示、モデルのルーティング、スマートなコンパクション、品質チェック、バージョン対応の最適化、スマートなルーティング）に従って、一度に 1 つずつ変更します。テンプレートは examples/ にあります。また、測定した数値とともに以下も提示します。

• python3 "$MEASURE_PY" recommendations：日次測定に基づく使用状況の推奨事項（コンパクト化ウィンドウ、サブエージェントのキャッシュ有効期間）。ユーザー自身の数値と、状態が recommend の場合の正確なコマンドも含まれます。該当する行はそのまま伝えてください。Token Optimizer は推奨のみを行い、どちらのキーも設定しません。
• python3 "$MEASURE_PY" subagent-cache status / compact-advice：各項目の根拠となる単一測定の詳細。どちらもユーザー自身の履歴に基づく推定値です。判断するのはユーザーです。
• スクリプトで代替できる、繰り返し行う作業：token-coach に引き継ぎ、goal e を指定します。

5. 検証。 検証エージェントが再測定して、削減量を算出します。変更前後の数値を提示してから、それを維持するための習慣を示します。

検証値がベースラインより悪化している場合は、原因となった変更を特定し、該当ファイルをバックアップから復元して、手順 4 に戻ります。

ユーザーのセットアップを変更する際のルール

これらのルールは、ユーザーが簡単には取り戻せない作業を保護するためのものです。

• 変更のたびにバックアップを作成し、適用前に差分を提示します。
• 削除せず、アーカイブします。アーカイブ先はスキルディレクトリの外にし、アーカイブが読み込まれないようにします。
• スキル、MCP サーバー、または拒否ルールをアーカイブする前に、それらに依存するものを確認し、影響を先に伝えます。
• グローバルな拒否ルールより、プロジェクトレベルの拒否ルールを優先します。
• ユーザーが個別の変更を承認しない限り、ユーザー自身の設定値は変更しません。
• 測定値（トークン数とウィンドウに占める割合）を引用します。削減効果はコンテキスト予算として説明し、measure.py が算出した場合に限り金額も示します。

参考資料

必要な内容	参照先
Codex、Cursor、OpenCode のワークフロー	references/codex-workflow.md、references/cursor-workflow.md、references/opencode-workflow.md
セットアップの詳細、Keep-Warm の同意	references/phase0-setup.md、references/keepwarm-consent.md
エージェントのプロンプト、トークンの流れ	references/agent-prompts.md、references/token-flow-architecture.md
調査結果の提示	references/presentation-workflow.md
実装手順、チェックリスト	references/implementation-playbook.md、references/optimization-checklist.md、examples/
CLI コマンド、セッションの継続性、エラー	references/cli-reference.md、references/session-continuity.md、references/error-recovery.md

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