token-optimizer-mcp

Token Optimizer MCP

バイト数ではなく、料金を最適化する圧縮です — 効果を確かめられるよう、ベンチマークも同梱しています。

オプティマイザーツール、ライブグラフの置換、すべてのエージェント、そしてグラフ自体のコストを記録する 1 つのローカル台帳。

HeadRoom との比較

プロバイダーはプロンプトのプレフィックスをキャッシュします。キャッシュされたトークンの再読み込みには0.1 倍、書き換えられたトークンには1.25 倍の料金がかかります。多くの圧縮ツールは削減したバイト数を最適化し、この倍率を考慮しません。このツールは料金を最適化します。

**実際の実装と、同じ実装のフィクスチャを使って測定しています。**再実装でも、こちらのフィクスチャを使ったものでもありません。相手のハーネスがペイロードを圧縮してダンプし、相手のリゾルバーが相手独自のマーカーを復元します。そして、こちらには同一のバイト列が渡されます。相手の列には、キャプチャしたホールドの 9 つの構成のうち、行ごとの最良値を掲載しています。

表にはこちらの方式を 2 つ掲載しており、それぞれ異なる問いに答えています。**oursはブロックを移動させないブロックエンジンで、MCP ツールとフックが実行する方式です。削除するものはすべて圧縮によって削除し、リクエストの外に出すことはありません。ours, proxy**は Claude Code のセッションが経由するプロキシです。圧縮できなかったブロックをファイルに移し、パスを示すマーカーを残します。これは、コンテンツキャッシュの参照方式が行うのと同じ種類の交換です。ours, presetは、spillWholeBlockBelow: 0.9でこの移動を有効にしたブロックエンジンです。

2026-10-17 に b1231a8c で記録。レコードの regenerate フィールドに記載されたコマンドを使用し、HeadRoom 0.37.0 独自のフィクスチャとハーネスを対象に測定しました。このアームは HeadRoom 自体を実行するため、CI では再計算せず、レコードに対してこれらの数値と出所を検証します。

コーパス全体では、プロキシは文字数を 82.5%、トークン数を 91.5% 削減します。相手の最良構成では、削減率はそれぞれ 51.5% と 61.4% です。何も取得し直さない場合、つまり相手のマーカーが想定する範囲の端では、18 行すべてで相手の最良アームより低コストです。移動したブロックをすべて取得し直す場合でも、18 行中 17 行で低コストです。ブロックエンジン単体では、文字数を 72.0%、トークン数を 55.9% 削減します。相手より文字数の削減率は高く、トークン数の削減率は低くなります。 現在も優れている点とその理由。 codebase-exploration、grep-output、 raw-build-log、sre-debugging、および生データの4行では、最良の方式で トークンを83.2～99.8％削減し、ブロックエンジンでは12.7～62.4％削減します。 これらの数値はコンテンツキャッシュを参照した場合のものです。ブロックを小さくするのではなく、リクエストから取り除いてストアに格納し、<<ccr:hash,kind,size>> マーカーに置き換えます。ブロックを格納する場所のないエンジンではこれに対抗できないため、これらの行では削減率で ours 列が劣り、何も取得しない場合はコストでも劣ります。プロキシも同じ処理を行います。これら8行のうち5行ではプロキシが上回り、grep-output と raw-build-log では同等、codebase-exploration では0.1ポイント下回ります。プロキシのコストが相手より高くなる唯一の行は agentic-conversation で、移動したブロックをすべて再取得する場合に限ります。相手はこの会話を一切外に移動しないため、どちらの時点でもコストは同じですが、プロキシは一部を移動し、必要な部分ごとに取得コストを支払います。

もう一方の列はターン数です。 マーカーはコンテンツそのものではありません。そこに示された内容を読むには、エージェントがリクエストを1回送る必要があります。コーパスに配置された13,792個の保持単位のうち、ブロックエンジンは5,223個をテキスト内に保持し、さらに8,569個をテキストだけから再構築可能な状態にするため、追加ターンなしですべて参照できます。一方、相手は6,711個をテキスト内に保持し、7,075個をストアに格納するため、取得呼び出しが1回必要です。こちらでは復元不能なものは0個、相手では6個です。 相手の最良の方式では、コーパス全体のコンテンツを取り戻すために17回の往復が必要ですが、ブロックエンジンでは0回です。プロキシは相手と同様、移動したブロックごとにターンが必要になります。このターン分のコストは、コストモデルの取得率側で計上されます。

相手のマーカーにかかるコストには、サイズだけでなくツールも含まれます。 相手のマーカーを利用できるのは、プロキシがリクエストに headroom_retrieve ツールも添付するためです。これはデフォルトで有効（ccr_inject_tool）であり、セッションで一度使われると、その後のすべてのリクエストにも添付されます。そのため、相手の最良の方式でマーカーが残る各行には、このツールの定義分も加算しています。これは相手自身のパッケージから bench/compression/headroom/ccr-tool.py を使って記録しました。最初にツールを追加するターンでは、その後ろにあるキャッシュ済みプレフィックス全体も書き換えられますが、これは加算していません。相手に有利な扱いです。こちらではツールは不要です。マーカーが示すパスは、エージェントがすでに持っている Read で開けます。また、パスの長さには、短く作った仮のパスではなく、プロキシが実際に書き込む長さ（<home>/.tok/<pid>/<15 digits>、src/compress/spill-path.ts）を使って計上しています。

browser-session は大部分がテスト用データによるものです。 このペイロードには画像が4枚含まれ、そのうち2枚は異なる画像です。また、画像内のbase64は写真ではなく生成されたものです。異なる画像の1枚だけでも160,032文字から5,572文字に縮小されますが、実際のPNG画像ではこのようなことは起きません。実際のセッションにも当てはまるのは重複です。画像のバイト数の半分は、リクエスト内にすでにある画像のコピーで、ペイロード全体の44.3％を占めます。マーカーが示す実行内容は出力内に残っているため、読み手は何も要求せずに再構築できます。このため、トークンよりも文字数のほうが大幅に減少します。どちらの方式でも、画像トークンはピクセルから数えられるためです。

表全体を再現するには：

python bench/compression/headroom/run-theirs.py <headroom-clone> <out-dir>

python bench/compression/headroom/resolve-theirs.py <headroom-clone> <out-dir>
node bench/compression/head-to-head.mjs <out-dir>

相手が公開している設計との比較

2つ目の方式では、相手のベンチマーク生成器の定義に基づき、公開されている設計を再実装します。つまり、不透明なハッシュマーカー、圧縮した履歴、取得ツールとシステムメッセージの挿入を行います。これにより、公開された比較対象がある4つのワークロードを、相手のクローンを使わずに検証できます。node bench/compression/proof.mjs：

codebase-exploration は、7.3ポイント差で彼らのものから私たちのものになりました。 この表の以前のバージョンでは、この項目の私たちのスコアを61.3%と記載し、その後は同等とし、さらに彼らの47.4%に対して46.0%という公開済みの敗北を記載していました。最初の2つはこのリポジトリではなくブランチの数値で、3つ目は記載時点ではこのツリーで正しい数値でした。その後、log エンジンへの4つのコミットで54.2%に上がり、連結ブロックの解析を保つためにブロック内のハッシュバンを隠す変更で64.9%になりました。すべてのマーカーに6文字のスタンプを付けて認証したことで0.2ポイント下がり、さらに、スピルしたファイルの名前をカウンター上の位置ではなく、プロキシシンクと同じように内容のダイジェストにしたことで、0.5ポイント下がって64.2%になりました。その後、見積もりではなく実際のトークン数を使うようになりました。上の表のすべての数値は、Anthropic独自のトークナイザーがテキストに対して返す件数になり、オフラインでも使えるよう、コミット済みのフィクスチャに記録されています。その条件では、この項目は**53.7%**です。また、このアームが作り出した32桁の16進数の名前ではなく、プロキシのシンクが実際に書き込むパス、つまり内容アドレス方式で10進数の名前を採用したことで、**54.7%**になりました。これはこの履歴で最大の変化であり、エンジンとはまったく関係のない唯一の変化です。文字数を4で割る方法では、コントロール側の16進数マーカーを過大に、私たちのスタンプを大幅に過小に見積もっていました。当時のスタンプは母音を含まない31文字の文字セットからなる6文字で、大きな文字セットからのランダムな文字列はBPEトークナイザーにとってほぼ最悪のケースです。そのため、実測では5.52トークンかかったのに、文字数÷4では2トークンとして計上されていました。ここに挙げた数値で誤った方向に動いたのは、この3つだけで、どれもリグレッションではありません。いずれも、ハーネスがそれまで計上していなかったコストを計上するようになった結果です。そのコストを把握できたからこそ、次の改善ができました。スタンプは現在9桁の10進数で、以前の6文字よりわずかに多くのエントロピーを持ち、生成のたびに4トークンかかります。以前は平均5.52トークンで、4〜7トークンの幅がありました。この項目で以前のスタンプと比較すると、同じツリー、同じフィクスチャで、スタンプだけを31文字セットの形式に戻した条件で、0.1ポイントの改善になりました。この0.1という数字が正直なところです。マーカー1個あたりのコストは4分の1以上下がりましたが、エンジンが出力する内容に占めるマーカーの割合は小さいため、見出しの数値の変化は1個あたりの節約分から想像するよりずっと小さくなります。文章に含まれる数値は、それを測定したツリーについての事実です。そのため、bench/compression/readme-table.check.mjs は、記載された数値をそのまま信頼するのではなく、ハーネスからすべて再計算します。

この再実装アームの4つの比較対象すべてに対して、4項目すべてで私たちが勝っています。 彼らの実際の実装と比較した答えは、このセクションの冒頭にある表のとおりで、全勝ではなく結果は分かれています。何も取得し直さない場合、プロキシはすべての項目で彼らの最良のアームより低コストですが、全体ではより多くのトークンを使います。一方、ブロックエンジンだけは、ラウンドトリップなしですべての識別子を保持しますが、彼らの最良のアームがリクエストからブロックを移動させる項目では、削減率で負けています。

2つの列は同じエンジンの異なるアームから算出されており、そこが重要です。v3-history は履歴も圧縮し、バイト単位で彼らと一致します。一方、v1-frontier はキャッシュ済みのプレフィックスをそのままにして、請求額を11〜42%抑えます。削除するバイト数を最大化することもできますが、デフォルトではありません。キャッシュ済みのプレフィックスではコストがかかるためです。

競合アームは、公開された設計をこのリポジトリで再実装したものであり、非公開のハッシュマーカー、履歴の圧縮、取得ツールとシステムメッセージの挿入を行います。彼らのバイナリではなく、私たち自身に適用するのと同じ署名付きコンテンツのガードを適用しています。

セッション全体での比較

node bench/compression/session-replay.mjs は、実際に記録された会話をターンごとに再生し、プロバイダーと同じ方法で料金を算出します。プロキシなしで、システムプロンプトとツールスキーマを含むリクエスト全体を、互いに独立した4つのセッションで比較しています。

ここは、ほかの方法では手が届かない領域です。会話履歴は実行中のリクエストの約65％を占め、ターンごとに増え続ける唯一の部分です。モデルの推論が蓄積されるため、セッションが長くなるほど節約効果も大きくなります。

エージェントのエンドツーエンドタスクでの比較

THOLで、プロキシなしの対照条件と実際の16タスクを比較しました。

• 16タスク中11タスクでコストが低減
• コストの中央値は0.926x、ターン数の中央値は0.671x
• 品質コストはゼロ：平均スコアは対照条件の0.994に対して0.994で、スコアが下回ったのは16タスク中0件

各タスクは1回ずつの実行のため、集計区間には依然として1.0が含まれます。確かなのは、タスクごとの集計とスコアの同等性です。ここに示した数値はすべて、コミット済みのベンチマークから再生成したもので、このリポジトリに同梱されています。

30秒でわかる概要

エージェントは、すでに済ませた作業にコンテキストの大半を費やしています。変更されていないファイルを読み直し、3行を見るためにファイル全体を出力し、上限のない検索を実行し、前回のセッションで導き出したのに忘れてしまった結論を再び導き出しています。

Token Optimizer は、4つの側面からこれに対処します。

1. コストの高い呼び出しを実行できなくします。 プラグインをインストールすると、200 KBのファイルに対する組み込みのReadは拒否され、拒否メッセージには、キャッシュ済みで差分を取得した代替手段が示されます。Grep、Glob、Edit、Writeや、シェル経由のcat／head／grep -rも同様です。このセッションですでに読み込んだファイルを再び読むと、差分だけが返されます。これは通常、最も大きな節約効果をもたらし、サイズに基づくルールでは原理的に捉えられません。有効化する設定はありません。

2. エージェントが導き出した内容を記憶します。 プロジェクトごとのナレッジグラフは、作業の副産物として知見、決定、行き詰まりを蓄積し、エージェントが関連ファイルに触れた時点でそれらをすぐに返します。知見を保持するコストは約150トークンです。再び導き出すには5,000～50,000トークンかかります。

3. 公開の場で自己計測し、効果が出ていないときは知らせます。 MCPのプログレッシブディスクロージャーについて、事前値と実際の返却値を実測します。後続の展開分は同じ純額から差し引きます。モデル化されたグラフの置換と、後続のグラフ効果を測定するランダム化対照群は、別個に扱われます。すべての数値は、実測済み、収集中、対象外、または未取得のいずれかとして表示されます。

4. トラフィックの出所を識別します。 返されたコンテキスト、任意のコスト換算値、回避できた純トラフィック量を、操作とMCPハンドシェイクの識別情報ごとにまとめます。Codex、Claude Code、Geminiなど、接続された各クライアントの行が個別に表示されます。識別情報のない古いレコードは、その時点で開いているエージェントに割り当てず、明示的に「未識別」として扱います。

アカウントもホスト型サービスも不要です。MITライセンスのため、業務でも利用できます。 測定は、あなたが求めない限り行われません。匿名の使用状況データはデフォルトでオフになっており、個別に2つのオプトインが必要です。TOKEN_OPTIMIZER_TELEMETRY=1 を設定すると、カウントが集計されてローカルディスク上のファイルに保存され、TOKEN_OPTIMIZER_BEACON=1 を設定すると、そのデータがアップロードされます。最初の設定だけではソケットは開きません。両方を設定すると、ディスク上にすでに保存されているイベントがセッション開始時に一度送信されます。まとめて送信され、処理のホットパスで送られることはありません。また、受信側が受け入れた後にのみファイルが消去されます。install_doctor は、どちらが有効か、保留中のイベント数、送信先を表示します。送信は行わずに報告します。アップロードキーなしでビルドされたパッケージは一切送信できず、オプトインが機能しているように見せかけることなく、その旨を doctor が知らせます。 DO_NOT_TRACK=1 は、ほかの設定にかかわらず、両方を無効にします。バージョンチェックの npm run doctor と install_doctor が行うのは、npm のインストール元レジストリへの単純な GET です。あなたに関する情報は一切含まれず、診断を求めた場合にのみ実行されます。セッション中に実行されることはありません。DO_NOT_TRACK=1 または TOKEN_OPTIMIZER_UPDATE_CHECK=0 を設定すると、ソケットが開かれる前にチェックが抑止されます。イベントには数値とフラグだけが含まれます。文字列は書き込まれる前に破棄されるため、パス、プロンプト、エラーメッセージが誤って送信されることもありません。マシン識別子はソルト付きハッシュであり、ホスト名ではありません。集計対象は、プロジェクトがすでに保持しているフック台帳です。ツールの代わりにグラフが応答した頻度、ホールドアウトの各群で何が提供され、何が差し控えられたか、そして節約量がコストを上回ったかどうかを対象とし、6時間ごとに整数へ集約されます。ファイル名を含む台帳そのものが送られることはありません。使用状況はリクエストごとの行ではなく、集計値としてカウントされます。200リクエストごとに1つのイベントを記録し、リクエスト数、入出力バイト数、圧縮が効果を発揮した頻度、ナレッジが注入された頻度、省略されたブロック数を保持します。さらに、プロキシ停止時に最後のイベントを1つ記録します。これにより合計値を正確に保てます。リクエストごとに行を記録すると、負荷の高いセッションではバッチが上限を超え、最初の500件しか報告できなくなるためです。その代わり、リクエストごとの分布は保持されませんが、下流で必要とされるものではありません。npm run doctor は、これらのうち何が有効か、何が記録されているかを正確に表示します。

実機でダッシュボードが証明すること

この README のスクリーンショットは、デザインモックアップではなく、リリースされたサーバーがローカルに永続化されたデータを読み込んだものです。上のキャプチャでは、次の内容が報告されています。

• 現在進行中の実証で、検証済みの MCP トランスポートトークンを正味43,491個削減しています。意図的に発生させた10,546トークンの増加を差し引いた、総削減量は54,037トークンです。
• 過去のトークン数／ツール報告によるトークン数486,074,740個を隔離しています。その大部分は、モデルのコンテキストに入らなかったリポジトリスキャンの量です。
• AiDotNet に対する Codex／Claude Code／Gemini の stdio のライブスモークテストを実施し、各クライアントを個別に識別しています。
• 11個のローカルプロジェクト全体で、グラフノード2,648個、エッジ6,527個、検出事項58件があります。
• 選択したローリング24時間の期間中に、アクティブな6つの CLI クライアント全体で、フック実行が1,000回超、失敗ゼロ、タイムアウトゼロです。
• モデル化されたグラフ置換の可能性は6,332トークン分です。因果グラフ再利用の調査が Collecting の間は、検証済みの主要な数値から除外されます。

ダッシュボードは現在、ネイティブ CLI の使用量レシートを読み込み、キャッシュされていない入力、キャッシュ読み取り、キャッシュ書き込み、出力の価格を、取得したプロバイダー、モデル、ルート、リクエスト時のティア、バージョン管理された公式ソースに基づいて正確に算出します。モデル ID が曖昧な場合は、根拠のない平均的な推測を割り当てず、価格未設定のままにします。API／公開価格相当額はプロバイダー報告の料金とは別に保持され、サブスクリプションの請求額と表示されることはありません。トークン計上の契約を参照してください。

クイックスタート

Claude Code — MCP サーバー単体ではなく、プラグインをインストールしてください。適用を強制するのはプラグインです。サーバーだけを追加すると、モデルが無視できるツールが使えるようになるだけです。

/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

インストールはこれで完了です。16 個すべてのクライアント →

その後、次に何をすればよいか知りたいときは、いつでも以下を実行してください。

token_audit

セッションあたりのコストが最も高いものを並べた、ひとつの優先キューです。月額コスト相当額は、ご自身の実効レートを設定した場合に限り、任意で表示できます。各項目には修正方法が記載されています。ダッシュボードでも、6 つのレポートでもなく、キューです。

サブエージェントとワークフロー

トークン消費が集中するのはエージェントです。長時間実行されるサブエージェントは、ターンごとにコンテキスト全体を再送信するため、ツールが追加するバイトはすべて、その後の各ターンでも再びコストになります。ある実測セッションでは、42 個のワークフローサブエージェントがモデルを 4,483 回呼び出しました。最も長時間実行された 6 個は、それぞれ 218～348 回呼び出し、コンテキストは最大 336K～609K トークンに達しました。合計で出力トークンを 4.0M、キャッシュ読み取りトークンを 1.0B 消費しました。請求額の原因は書き込みではなく、再読み込みです。

設定なしで機能すること

プラグインのフックは、メインセッションと同様にサブエージェントでも実行されます。エージェントごとの設定は不要です。

• ファイル全体の読み取りは、Read 経由でもシェル経由でもアウトライン化されます。 エージェントは主に cat、type、Get-Content を使ってファイルを読み、Read はほとんど使いません。実測セッションでは、シェル経由の読み取りが 2,071 回、Read 呼び出しは 9 回でした。大きなソースファイルを初めて全体読み込みすると、どちらの方法でもファイルの代わりに、シンボルの行番号付きアウトラインが返されます。同じファイルを 2 回目に全体読み込みすると、ファイルそのものが返されます。行範囲がアウトライン化されることはありません。sed -n 'A,Bp'、head、Get-Content -TotalCount、ページ指定した Read は、すべてそのまま通過します。
• 各サブエージェントには、一度だけ概要が伝えられます。 サブエージェントには SessionStart のガイダンスが表示されないため、最初のツール呼び出しに代わりに 4 行の概要が付加されます。ツールが一覧にある場合は読み込むこと、ファイル全体ではなく範囲を読むこと、最終レポートを短くすることが伝えられます。ツール名は条件付きでのみ記載されるため、フックのみのインストールで、存在しないツールを呼び出すよう指示されることはありません。
• アドバイザリは一度だけ表示されます。 「smart_grep を使う」のようなルーティングのヒントは、該当するコマンドのたびにではなく、呼び出しの種類ごとにエージェントあたり最大 1 回表示されます。
• 過去の調査結果は、実行中のコマンドを明示している場合にのみ提示されます。 明示的なトリガーがない調査結果がコマンドとともに提示されるのは、主張にそのコマンドのプログラムとサブコマンドの両方が記載されている場合（npx jest や dotnet build など）に限られます。単語をひとつ共有しているだけでは提示されません。
• **ビルドとテストの出力の繰り返しは、**メインセッションと同様に、量が制限されます。
• プロキシ経由では、要求した範囲がそのまま返されます。 ページ指定した Read やシェルのスライスが折りたたまれることはなく、ファイル全体の読み取り内で折りたたまれた場合も、ファイル自体の行番号が示されます。

エージェントに概要を伝える際に追加すること

Claude Code は、サブエージェントに MCP ツールを 遅延 ツールとして提供します。スキーマは、エージェントが要求するまで読み込まれません。読み込まないエージェントはシェルコマンドに頼ることになります。エージェントのプロンプトに以下を記載してください。

Before your first file read or search, load the token-optimizer tools:
ToolSearch("smart_read smart_grep smart_glob").
Use smart_read for files (it returns a diff on re-reads), smart_grep for
searching, and smart_glob for finding files. Do not print whole files or search
the tree through the shell. When you need part of a file, read a line range.

サーバー独自の指示でも、遅延ツールかどうかにかかわらず、すべてのクライアントに同じ内容が伝えられるようになりました。

エージェントの実行時間を短く保つ

プラグインが縮小できるのは、エージェントのコンテキストに入る情報だけです。ターン数と、エージェントが保持するコンテキストのサイズは、作業の分割方法によって決まります。

• エージェントごとに、範囲を限定したタスクをひとつ割り当てます。 それぞれが小さなコンテキストで開始するため、数百ターンにわたって実行されるエージェントをひとつ使うより、短いエージェントを複数使うほうがコストを抑えられます。
• エージェントが必要とする事実（パス、行番号、具体的な質問）を渡し、エージェントに探し直させないようにします。
• 構造化された結果を求めることで、答えが出た時点でエージェントが停止するようにします。

エージェントを測定する

各サブエージェントは、セッションのトランスクリプトと並んで、~/.claude/projects/<project>/<session>/subagents/ に独自のトランスクリプトを書き込みます。各アシスタント行の usage ブロックには、input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens が記録されます。

各応答は一度だけ数えてください。 1 回のモデル応答は、同じ message.id を持つ複数のアシスタント行として書き込まれ、各行にはその時点までに記録された使用量が繰り返し記載されています。各 message.id について最後の行を保持してください。そこに最終的な使用量が記載されているので、それらを合計します。すべての行を合計するとコストを過大評価します。上記のセッションでは、キャッシュ読み取りトークンが 10 億ではなく 18 億と報告されました。反対に最初の行を保持すると、出力が 400 万ではなく 50 万となり、過小評価されます。

異なる message.id の数が、エージェントが行ったモデル呼び出しの数です。これを最大コンテキストと照らし合わせれば、エージェントを分割すべきだったかどうかがわかります。

ナレッジグラフ — ほかにはないもの

すべてのエージェントセッションは、同じ形で終わります。推論は消えてなくなります。次のセッションでは、同じ推論を何度も、毎回全額をかけてやり直します。

これはプロジェクトごとの進化するグラフを構築します。ファイル、シンボル、タスク、発見事項をノードとして、derived_from、contains、supersedes、contradicts、related をエッジとして、実際の作業から自動的に情報を蓄積します。取り込みジョブも、埋め込みモデルも、再構築の手順も、組み立てるクエリも必要ありません。

you touch  src/auth.ts
           │
           ├─ verify() compares exp against the LOCAL clock          (finding, 0.9)
           ├─ per-host retry budgets; global was rejected — deadlock (decision)
           ├─ ! the skew fix was reverted once already               (dead end)
           └─ [git] 47 changes in 90d, last three: "fix token expiry",
                    "revert skew fix", "fix token expiry again"

こうした情報は、リポジトリには存在しません。エージェントが一度トークンを費やして見つけ出したからこそ存在するものであり、ほかのすべてのツールはセッションの終了時にそれを捨ててしまいます。

デフォルトのインストールで実際に生成されるもの。 ファイル、シンボル、タスク、およびそれらの間のエッジからなる構造グラフは、設定なしで通常のツールの利用履歴から取得されます。発見事項は 2 通りの方法で生成されます。セッション終了時に、derive がすでにディスク上にある証拠（コマンドの結果と終了コード、赤から緑への変化、修正、再読み込みの繰り返し）を読み取り、そこから発見事項を書き込みます。モデル呼び出しも、認証情報も、外部への送信もありません。また、アクティブなモデル自身も wiki_write を通じて、永続的な結論を記録します。

モデルベースのセマンティックハーベストは 3 つ目の方法であり、すでには持っていないものが必要なのはこれだけです。オプトインではありません。TOKEN_OPTIMIZER_HARVEST=0 にすると オフ になりますが、実際の条件となるのは認証情報です。認証情報がなければ off:no-key と報告されます。これは CI、企業のマシン、サブスクリプションのみのログインでの状態です。TOKEN_OPTIMIZER_HARVEST_ENDPOINT をローカルモデルに設定すれば、無料かつプライベートに、マシンの外へ何も送信せずに実行できます。npx token-optimizer-doctor を実行すると、どの方法が有効か確認できます。

なぜこれは RAG ではないのか

トラバーサルと語彙検索の組み合わせは、決定的で、瞬時に動作し、説明可能で、オフラインでも使えます。

ゼロターン拒否

単に拒否するだけでも、1ターンを丸ごと消費します。モデルがReadを呼び出し、拒否され、再計画してから、smart_readを呼び出します。しかし、拒否する時点ですでにファイルと、グラフに保存されたスナップショットの両方を保持しているため、拒否の中に答えが含まれています。再計画も、2回目の呼び出しも不要です。ターンのコストは1から0に下がります。

また、ツール出力の根拠となる判定がすでにグラフに保存されている場合、その出力はコンテキストに入りません。圧縮されるのではなく、そもそも存在しません。

ダッシュボード

npm install
npm run build
npm run dashboard      # http://localhost:3100

概要では、トークンオプティマイザーがまず答えるべき質問を確認できます。

1. どれだけのMCPコンテキストを回避できましたか？ 主要な数値は、実体化されたペイロードの総削減量から、後続のリンクされた展開分をすべて差し引いた値です。グラフの推定値は意図的に別枠で表示されます。
2. それでもエージェントに届いたコンテキストはどれだけですか？ 成功した現在のMCP結果は、有効な処理前の状態がない場合でも、実際に返されたテキストをすべて記録します。この行はコンテキストとして記録されますが、削減量は測定されません。
3. どのエージェントが、どのアクションにそれを費やしましたか？ クライアント台帳とアクションテーブルには、操作、返されたコンテキスト、任意のコスト換算値、回避した正味のトークン数が表示されます。ライフサイクルのみを扱うクライアントは「測定対象外」と表示され、ゼロとして捏造されることはありません。
4. 記憶するためのコストは、節約分を上回りましたか？ 配信と意味情報の抽出に使われたトークンはグラフのコストに計上されます。処理群と対照群のエビデンスゲートを通過した後にのみ、因果的な便益が加算されます。

ウォークスルー：空のダッシュボードではなく、有用なデータを得る

1. MCP サーバーと、CLI 用のネイティブアダプターをインストールします。MCP ハンドシェイクではクライアントごとの記録が行われます。ネイティブのライフサイクルフックでは、クライアントプロトコルが許す範囲で、ルーティング、キャプチャ、ヘルスチェック、配信が自動的に行われます。
2. 通常どおりsmart_read、smart_grep、smart_glob、smart_edit、またはその他のMCP操作を使用します。成功した結果はすべて、返されたコンテキストを記録します。比較可能な実体化済みの処理前状態があるツールは、総削減量も記録します。後続のexpand呼び出しでは、その削減量から差し引かれます。
3. アクティブなモデルに、wiki_writeを使って永続的な結論を記録させます。新しいエージェントが作業を再導出する前に、プロジェクトまたはこれから扱うファイルについてwiki_readを呼び出します。ネイティブクライアントでは、一致するナレッジを自動配信することもできます。 グラフを直接読むにはwiki_queryを使います。キーによる調査結果1件の取得、主張を対象にしたBM25ランキング検索、近傍ノードを含めたノードの取得、グラフ独自の監査が可能です。これにより、SessionStartのブリーフィングを受け取らないサブエージェントも、過去のセッションで確立された情報にアクセスできます。
4. http://localhost:3100を開きます。統合された記録には概要、キャプチャの健全性、グラフの探索、監査、因果関係のエビデンスには把握している内容を使用します。
5. ソースを読み込まずに既存のローカルリポジトリを登録するには、npm run projects:discover -- /absolute/path/to/reposを実行します。これによりカバレッジの不足が明確になりますが、調査結果を捏造することはありません。

メンテナー向けに、このライブスモークテストでは、提供されているstdioトランスポートをテストし、分析データベースにデータを事前投入せずに、個別に帰属先を示した行を作成します。

npm run dashboard:attribution-smoke -- /absolute/path/to/project /absolute/path/to/large-file
npm run dashboard:verify-live -- http://localhost:3100

ヘルスパネルは、生のテキストをそのまま表示するのではなく、運用状況を確認できるように設計されています。各クライアントについて、アクティビティ、ランタイムの失敗やタイムアウト、ポリシーの適用結果、観測された対象範囲を確認できます。診断情報にプロンプト、コマンド、パス、ツール出力は含まれません。

ドラッグして回転し、スクロールしてズームします。ノードをクリックすると来歴を確認でき、範囲を限定した 1 ホップのフォーカスビューにも切り替えられます。デフォルトの すべての既知のプロジェクト のスコープでは、不透明なプロジェクト ID を通じてローカルグラフを集約します。ファイルシステムのパスがブラウザーに渡ることはありません。

監査タブ。 矛盾、古くなった調査結果、確信度の低い主張を、モデルの真実としてひそかに扱うのではなく、確認できる状態に保ちます。

エビデンスコンソール。 クライアント／モデル／タスクのコホート、95％区間付きのマッチング済み効果、ライブの結果結合、害に関するフィードバック、および 16 クライアントすべての機能階層を表示します。エビデンスが不足している間は、リリースや優位性に関する主張をすべてフェイルクローズします。

ワンクリックの Markdown エクスポート。 蓄積されたグラフを、確認、編集、コミットできるドキュメントに変換します。

設計上、サーバー側で処理します。ブラウザーが要求するのは、近傍、検索結果、またはページです。成熟したグラフには数千のノードが含まれ、グラフ全体を送信すると、20 個の項目しか表示しないビューのために、ページを読み込むたびに数メガバイトをダウンロードすることになります。

デフォルトの すべての既知のプロジェクト のスコープでは、不透明なマシンローカルのプロジェクトレジストリを通じて取得済みグラフを統合します。ファイルシステムのパスがブラウザーに渡ることはありません。ライフサイクルフックは、リポジトリが使用されると登録します。ソースファイルを読み取らずに既存のローカルチェックアウトをバックフィルするには、明示的に指定した 1 つ以上のルートに対して、範囲を限定した検出コマンドを実行します。

npm run projects:discover -- /absolute/path/to/repos /absolute/path/to/worktrees

カバレッジでは、グラフデータがあるリポジトリと、既知ではあるものの取得が始まっていないリポジトリを区別します。バランスカードは永続化されたイベントに基づいています。 メモリの提供 は、エージェントに実際に供給されたグラフコンテキストの数を数えます。 比較用に保持 は、ランダム化された対照群のタッチ数を数えます。 記憶のコスト は、提供されたコンテキストのトークン数と、測定されたセマンティック書き込みペイロードのコストを組み合わせます。 回避された読み取り は、下流結合を伴う処置対象のファイルタッチが少なくとも 20 件、保留群が 5 件に達するまで、Collecting または Not measured のままです。ダッシュボードは、データがない状態から節約の推定値を捏造しません。

クライアント間の機能契約と ライブ評価スイートを参照してください。

クライアント間のライフサイクル診断

Claude Code のカスタムルーターやコンパクション経路も含め、すべてのネイティブフックが同一形式の、範囲を限定した JSONL ライフサイクルレコードを書き込みます。レコードには、クライアントとプラグインのバージョン、イベント、ハッシュ化されたセッション／ターンの相関情報、レイテンシー、結果、入力／出力のバイト数、レスポンスのキー構造が含まれます。プロンプト、コマンド、ツール出力、ファイル内容、生の作業ディレクトリパスは意図的に保持しません。フィールドには OpenTelemetry のログ重大度とリソースのセマンティクスが含まれているため、別のスキーマを新たに作ることなくローカルファイルを収集できます。

npm run diagnostics                         # last 24 hours, summary-first JSON
npm run diagnostics -- --hours 72 --output hook-summary.json
npm run diagnostics -- --include-events --limit 100 --output hook-report.json

生のイベント行はオプトイン方式で、最大 1,000 件に制限されます。デフォルトのレポートには、集計された健全性情報と、直近の失敗／タイムアウトが最大 20 件含まれます。これにより、通常のトラブルシューティング出力を CLI やモデルのコンテキストウィンドウに収まるサイズに保ちます。

ダッシュボードの 取得の健全性 パネルには、クライアント別の実行数、失敗数、タイムアウト数、および p50／p95 レイテンシーが表示されます。ログは 5 MiB でローテーションし、最大 40 ファイルを 14 日間保持します。状態ディレクトリが設定されている場合は .token-optimizer/logs に、設定されていない場合は ~/.token-optimizer/logs に保存されます。TOKEN_OPTIMIZER_LOG_DIR、TOKEN_OPTIMIZER_LOG_MAX_BYTES、TOKEN_OPTIMIZER_LOG_MAX_FILES、TOKEN_OPTIMIZER_LOG_RETENTION_DAYS を設定すると、これらの運用上のデフォルトを上書きできます。

他のオプティマイザーにはない機能

キャッシュを壊さず、重要な情報も失わない圧縮

オプションのローカルプロキシは、モデルに送信する際にツールの結果、検索出力、ログ、会話履歴を圧縮します。フックではこれを実行できません。PostToolUse の出力スキーマは {hookEventName, additionalContext?, classifierContext?} であり、クライアント内のどこにも updatedOutput は存在しないため、フックはコンテキストを追加できても結果を置き換えることはできません。プロキシが結果を置き換えようとすることもありません。結果がすでに履歴として含まれている、送信リクエストを書き換えます。

単に圧縮を強めるのとは異なる点が２つあります。

キャッシュされたコンテンツは書き換えません。 キャッシュされたプレフィックスの料金は 0.1x、キャッシュへの書き込みは 1.25x です。そのため、履歴を圧縮するとトークン数を減らせても、料金が増えることがあります。独自のベンチマークで測定したところ、キャッシュのブレークポイントより後ろを圧縮すると、すべてのワークロードで生のトークン数はさらに減りますが、すべてのワークロードで料金は高くなります。圧縮はフロンティアで停止し、料金計算で重み付けしたトークン数を生のトークン数と並べて報告することで、この落とし穴を推測ではなく明確に把握できるようにしています。

重要な行を残します。 長い配列の最初の数行以降を省略すると、この検索ペイロードでは 95.7％のスコアを記録しましたが、そこに仕込まれていた UUID レコードとエラーレコードの両方が失われました。どちらも、検索する価値のある唯一の２行でした。現在、エンジンは形状から外れた行を、どこにあってもすべて保持します。重要な値を保ったまま 92.4％を達成します。サイズの指標だけでは圧縮と切り捨てを区別できないため、ベンチマークのゲートでは、仕込んだ重要な値が失われた場合にビルドを失敗させます。

各方式で書き換えが許可されているコンテンツを対象に、HeadRoom が公開している４つのワークロードに一致するフィクスチャで測定した削減率は、このセクションの前半にあるガード付きの表のとおりです。72.8％、92.1％、92.2％、47.4％に対して、97.5％、97.8％、98.6％、54.7％です。ここで一度だけ示して確認し、重ねて記載していません。そうしなければ、ツリーが移動した後も、このコピーには 98.9％、98.2％、92.8％、61.3％と記載されたままになっていたでしょう。

これらは HeadRoom のコーパスではありません。コーパスは公開されていないためです。コードのワークロードでは、このリポジトリの実ファイルを読み込み、それ以外は、独自のベンチマークジェネレーターの定義に基づき、公開済みのワークロードの形状と規模に合わせて生成しています。

削減率は料金ではなく、この２つは一致しません。 キャッシュによって計算方法が変わります。キャッシュされたプレフィックスは再読み込み時に 0.1x、書き換えられたものには 1.25x の料金がかかるため、ある方式ではバイト数をより多く削減しても、料金が高くなることがあります。node bench/compression/proof.mjs を実行すると、まさにそうなります。HeadRoom 方式の設定はすべてのワークロードでより大きな割合を削減しますが、すべてのワークロードでキャッシュの料金を加味した実効トークン数では劣ります。

競合側の設定は、公開された設計をこのリポジトリで独自に再実装したものです。内容の不透明なハッシュマーカーを使い、履歴を圧縮し、取得ツールとシステムメッセージを注入します。相手側のバイナリではありません。可能な範囲で勝てるように実装しており、生の削減率では６件すべてで相手側が上回ります。

セッション全体での比較。 node bench/compression/session-replay.mjs は、実際に記録された会話をターンごとに再生し、プロバイダーと同じ方法で各会話の料金を計算します。先頭から続く最長のバイト単位で同一の部分には 0.1x、それ以降のすべてには 1.25x の料金がかかります。プロキシなしの場合と比較し、４つの独立したセッションを対象に、システムプロンプトとツールスキーマを含むリクエスト全体を測定します。

このリプレイは保存済みのトランスクリプトを使用しており、それは推論テキストを破棄しつつシグネチャを保持します。したがって、その削減量は有用な推論が圧縮後も残ることを証明するものではありません。また、競合他社の設計に対する当社の再実装を使用しています。これはオフラインでの推定値であり、彼らが提供しているプロキシでの結果ではありません。

HeadRoom の提供プロキシに対するライブ比較。 コミット f712b4ec に記録されたバランス型 4 アーム実行では、bench/live/ab.sh を使用し、各アームをすべてのポジションでローテーションし、各タスク後に pytest を個別に再実行しました：

加重入力は input + 1.25 * cache_creation + 0.1 * cache_read です。出力コストは含まれません。下限ゼロの Token Optimizer と HeadRoom はいずれも、この指標を対照比で約 64% 削減しました。Token Optimizer は HeadRoom より約 0.9% 多く使用しました。この小さな算術修正タスクは、タスク全体、圧縮品質、総コストにおける優位性を証明するものではありません。ローテーションは実行ポジションをバランスさせますが、共有プロバイダーキャッシュの影響が消えることを保証するものではありません。

HeadRoom 0.37.0 に対する Codex の 3 タスク比較（2026-09-18）。 3 つの合成制御読み取りタスク、3 回の繰り返し、3 つのアーム、すべてのアームをすべてのポジションで。27 回の実行すべてが正解を返したため、これは精度ではなく、同等の正しさにおけるコストを比較しています。HeadRoom は --mode token で実行されました。これはその圧縮優先設定であり、キャッシュヒット率を固定するために存在する cache デフォルトではありません。

対照に対する入力削減は、ログタスクで 22.7%、JSON タスクで 34.3%、コード検索で 11.5% でした。HeadRoom に対しては、54.9%、10.0%、42.2% でした。すべてのタスクで、両方の比較においてこのプロキシが優位であり、JSON 列は HeadRoom が最も強く、その差が最も小さいところです。

そのメカニズムは、独立して動く 2 つの数値に表れています。リクエストあたりの平均入力は、ここでは 14,156 で、HeadRoom の 16,529、対照の 18,544 に対してです。両方のプロキシが圧縮し、こちらはより強く圧縮します。実行あたりの平均リクエストは 3.0 で、対照と同じであり、HeadRoom の 4.3 に対してです。エージェントが後で読み戻さなければならないコンテンツを省略する圧縮器は、それを回復するために 1 ターン費やします。そしてこれらのワークロードでは、1 ターンのコストが省略によって節約された分よりも大きくなります。これが、このプロジェクト自身の遅延下限が回避するために存在する失敗であり、余分な 1.3 リクエストの正体です。 これが示していないもの。これらはトークン数であり、ドルコストではなく、 bench/live/report-codex.mjs は意図的にこれらを価格換算しません。3つの短い 合成ワークロードでは、普遍的な優位性を立証できません。各タスクはナレッジグラフのない 新規の一時ワークスペースで実行されたため、グラフ注入は何も寄与せず、これは 圧縮のみを測定しています。キャッシュされたトークンは入力列のサブセットであり、 追加の課金ではありません。HeadRoom の圧縮は、自社リスナーで記録したバイト数ではなく、 プロバイダーの使用量から採点されます。

HEADROOM_MODE=token node bench/live/codex.mjs で再現し、次に node bench/live/report-codex.mjs <evidence-dir> を実行します。上記の数値は、 そのレポーターが valid: true を balanced: true および失敗なしで返した後にのみ 読み取られました。以前の4回のキャンペーンは公開せずに破棄されました。1回は HeadRoom の [proxy] extra なしで実行されたため、すべての HeadRoom 実行が レディネス前にエラーになり、1回は HeadRoom をその cache デフォルトで実行し、 1回は不完全なリクエストキャプチャのためレポーターによって無効化され、1回は ホストディスクが満杯で ENOSPC により停止しました。

その後の Claude Code のデフォルト対アグレッシブの確認は、Claude の週次使用量 制限に達し、不完全です。その欠落した使用量を勝利として数えることはできません。 Codex の検証は Responses API を通じて独立して実行されます。

最新の Codex 共同確認（2026-09-16）。 凍結された12ファミリーの研究は、 インストール済みの HeadRoom 0.37.0 に対して120ペアを完了しました。当社のプロキシは 119/120 試行に合格し、HeadRoom は 120/120 に合格しました。1回のローカル割り当て クラッシュにより使用量が不明のまま残りました。77件の厳密な共同勝利（合格、 より安価、かつより高速）、20件のコストのみの敗北、12件の速度のみの敗北、9件の 両指標での敗北、より高コストだった同時刻の1ペア、そして失敗した試行がありました。 完全に測定された119ペアのみにおいて、推定トークンコストは26.9%低く、 エージェント時間は30.1%低くなりました。JSON のエージェント時間は5.6%高くなりました。 同時ファミリーごとの基準を満たしたのはログとリファクタリングのみで、研究全体の 優位性ゲートは失敗しました。これらの結果は、すべてのタスクがより安価またはより高速で あることを立証するものではありません。測定されたビルドは明示的な null を保持し、 完全な数値表を維持し、変更されていないペイロードのコピーを回避します。 完全な結果、すべての敗北、および保持されたクラッシュをご覧ください。

以前の拡張ローカル Codex 確認。 事前登録された7ファミリーの研究は、 インストール済みの HeadRoom 0.37.0 に対して70ペア / 140試行を実行しました。当社の 凍結されたプロキシは 70/70 に合格し、HeadRoom は 69/70 に合格しましたが、 1件の上流 HTTP 503 と使用量の欠落がありました。したがって完全台帳ゲートは失敗しました: 優位性は立証されませんでした。完全に測定された69ペアのみにおいて、記述的な 合計は当社のプロキシで推定コスト25.7%低減、入力38.9%低減、エージェント時間30.0% 低減でした。JSON は依然として敗北でした（推定コスト35.1%増）。 プロトコル、すべての試行、および制限事項をご覧ください。

その後の稀な文字列グループの修正は、その JSON の敗北を対象としています。完全に 測定された3つの新規ペアでは、HeadRoom と比較して入力が17.7%、推定コストが13.4%、 エージェント時間が13.6%減少し、それぞれ3リクエストでした。4番目のペアでは、 当社のアームで上流の503が保持されました。測定された1ペアは依然としてコストが 高くなりました。これらは開発結果であり、新しいビルドや全ワークロードでの勝利の 確認ではありません。完全なスクリーニングと除外をご覧ください。 最新的 Codex 研究の修正。 次の固定70組のスケジュールが完了しました。 当社のプロキシは69/70件、HeadRoomは70/70件で合格しました。当社の残りの試行では、 使用量が不明な上流の503エラーが発生したため、厳密な優位性は立証されませんでした。 完全に測定できた69組のみを対象とすると、推定コストは27.9％、入力は44.2％、 エージェント時間は31.7％削減されました。JSONの27.5％削減を含め、各ファミリーの 平均コストはすべて当社のプロキシが優位でしたが、個別の組では依然として13組で コストが上回りました。この実行には、ケース間のファイルハッシュ処理の失敗に対する 開示済みの修正が含まれます。元の製品とスケジュールは変更されていません。 完全な結果、修正内容、保持された失敗を参照してください。

完全一致検索の行、その後の開発。 すべての識別子と値を保持しながら宣言構文を 共通化したことで、コードサイズの差が解消されました。元の40件の敗北入力では、 アーカイブ済みのHeadRoomよりバイト数が37.5％少なくなりました。新たに用意した ローカルケース8件でも、送信バイト数が少なくなりました。バランスを取ったライブ比較 4組はすべて監査に合格し、当社の推定トークンコストは50.1％、入力は44.8％、 エージェント時間は51.1％削減されました。これは小規模な開発上の追加検証であり、 より広範な研究とは別です。取得した本文、再構築チェック、ライブ証拠を参照してください。

コスト敗北の追加検証（2026-09-16）。 敗北した13組すべてを調査し、IDプレフィックスの 厳密な共通化と、切り詰められたシェルエンベロープ内のレコードのサポートを実装しました。 これら13ケースの固定された追加検証では、26回の試行すべてに合格し、13組中12組で 当社のプロキシが優位となり、推定総コストが33.4％削減されました。残る敗北から、 外側のエンベロープに関するバグが明らかになりました。これを修正した後、バランスを取った 管理下の比較2組では、どちらも当社のプロキシが優位となりました。4回の試行すべてに 合格し、推定コストは34.3％、入力は15.9％削減されました。これらの開発実行では、 元の敗北をすべて保持しています。キャッシュやモデルの変動も結果に影響します。 ケースごとの監査、修正、厳密な再実行、ライブ証拠を参照してください。

ローカルプロキシのパフォーマンス（2026-09-16）。 インストール済みのHeadRoom 0.37.0を 相手に、繰り返しのログと一意のログ、JSON、コード検索出力を対象として、ローテーションした 3種類の順序で、ローカル上流へのリクエストを2,160件完了しました。当社の平均レイテンシと プロセスCPU使用量は、6つのグループすべてで低くなりました。サンプル取得したプロセスツリーの ピーク・プライベートメモリは80.0 MiBで、HeadRoomは1,909.9 MiBでした。これはメモリ使用量であり、 割り当て量ではありません。一意のコードでは、依然として転送バイト数が5.7％増加しました。 このスループット測定ではHeadRoomのレート制限を無効にし、圧縮設定はデフォルトのままにしました。 これらの測定は、モデルの品質や請求コストを測定するものではありません。 生データ、再現コマンド、制限事項を参照してください。

Codexのライブ比較（2026-09-15）。 ローカルのCodex CLI 0.154.0、gpt-6-astra、 およびインストール済みのHeadRoom 0.37.0を用いて、バランスを取った27回の実行を完了しました。 3つのアームすべてが9つのタスクすべてに合格し、最初の読み取りはすべて完全で、 プロバイダーの台帳合計はすべてCodexが報告した使用量と一致しました。

これらの件数にはキャッシュ済み入力と追加の取得ターンが含まれます。生の圧縮率や ドル建てコストではありません。出力トークンは、すべてのワークロードで改善したわけでは ありません。Codexの証拠と制限事項および 再現手順を参照してください。この3つの合成タスクだけでは、 あらゆるワークロードでの優位性は立証されません。 27 回の自然なワークフローによる開発テストもすべての実行で合格し、リトライを伴うバグ修正、複数ファイルのリファクタリング、設定の更新において、インストール済みの HeadRoom と比べて合計入力がそれぞれ 35.5％、43.5％、16.6％少ないことを測定しました。これらは、自然なツール選択を行う小規模な合成リポジトリです。キャッシュされていない入力とレイテンシーについては個別の結果があります。詳しくはワークフローのエビデンスと制約をご覧ください。

プロキシはデフォルトで有効になり、ループバックインターフェースのみにバインドされます。

これで、当方から何も起動しなくても有効になります。 7.1.0 までは、当方のラッパー経由でクライアントを起動しなければルーティングされませんでした。そのため、/plugin でインストールした後、ショートカットや IDE、デスクトップアプリから Claude Code を開いた場合、何も節約されませんでした。さらに doctor は、機能がそもそも適用されない状況ではなく、インストールの不具合として報告していました。インストール時に Claude Code 自身の settings.json へエンドポイントを書き込むようになりました。これは、当方が起動していないセッションでも読み込む唯一の設定であり、小さなバックグラウンドプロキシがそのリクエストを処理します。安全に有効化するためのルールは 4 つあります。

• 記録されます。 書き込まれる値はすべて、書き込み前の値とともに保存されます。 token-optimizer-uninstall --apply で正確に復元できます。また、値がすでに当方の書き込んだものではなくなっている場合は、復元を拒否します。変更した場合は、その値は再びあなたのものです。
• 期待に頼って書き込みません。 エントリーが追加されるのは、プロキシが実際にそのルートを処理した後だけです。停止中のポートを指す設定ファイルがあっても、穏当に機能低下するわけではありません。クライアントがプロバイダーにまったく接続できなくなります。
• 自己修復します。 チェックは、最初のモデルリクエストより前の各セッション開始時に再実行され、ルートを処理できなくなった時点でエントリーを削除します。
• 当方のものでない設定には手を加えません。 すでに別のローカルプロキシを指しているクライアントには変更を加えず、解析できない設定ファイルも書き換えません。

ラッパーのみの動作を維持するには TOKEN_OPTIMIZER_DEFAULT_ROUTING=0 を設定してください。ローカルのバックグラウンドサービスを一切使用しない場合は TOKEN_OPTIMIZER_PROXY_AUTOSTART=0 を設定してください。どちらの場合も、すでに書き込まれているエントリーは元に戻されます。

管理対象コマンド。 グローバルな npm インストールでは、ライフサイクルスクリプトが有効な場合、Claude のフックを有効にし、実際に利用しているクライアントコマンド（claude、codex、gemini、opencode、qwen、crush、droid、cn（Continue）、copilot、amp）を、Command Prompt、PowerShell、Bash、Zsh でラップします。ラップ対象は PATH 上にすでにあるコマンドだけなので、このツールをインストールしても、未インストールのクライアント名を占有することはありません。PATH から見えない場所にクライアントがある場合は、TOKEN_OPTIMIZER_MANAGED_CLIENTS にカンマ区切りのリスト（または all）を指定してください。0 を指定すると、シェルの有効化を完全にスキップします。Windows へのインストールでは、管理対象の .cmd ランチャーが User PATH に追加されるため、プロファイルや PowerShell の実行ポリシーを変更する必要はありません。ローカルインストールの場合やライフサイクルスクリプトが無効な場合は、token-optimizer-install を実行してください。更新された PATH とシェルの有効化を読み込むには、ターミナルを再度開いてください。管理対象の各セッションは独自のプロキシを起動し、パッケージに含まれるコア MCP ツール（wiki を含む）を登録して、終了時にプロキシを停止します。 token-optimizer-run <client> ... は、シェルの有効化なしでも動作します。

ルーティング可能なクライアントと、できないクライアント。 10 個のクライアントにはモデルのトラフィックをリダイレクトするサポート対象の方法があり、上記に記載されています。Claude Code と Gemini はプロバイダーがそれぞれ 1 つだけなので、インストール時にルーティングされます。その他のクライアントは、それぞれの設定でプロバイダーを選択し、その設定でエンドポイントを指定するとルーティングされます。推測で転送すると、あるプロバイダーの認証情報を別の会社へ送ることになるためです。ルーティングできないクライアントは 6 つあります。Cursor、Cline、Windsurf、Kilo、Roo、Zed はエディターのプロセス内でアシスタントを実行し、文書化されたリダイレクト手段を公開していません。オプティマイザーのツール、グラフ、フックなど、その他の機能は引き続き利用できます。doctor はこの制約を失敗として数えず、その旨を報告します。 token-optimizer-route には、実行中の内容と、ユーザーに代わって書き込まれた設定が表示されます。ルーティングを設定できる唯一のクライアントであり、こちらで設定できないのは Zed です。Zed のプロバイダーは、エディター内で選択する名前付きエントリであり、どのエンドポイントとモデルを使うべきかを把握しているのはユーザーだけです。

token-optimizer-route                                                  # what is routed right now
token-optimizer-route zed --upstream https://api.openai.com/v1 --model gpt-4o
token-optimizer-route zed --remove

ここで使用している Zed のプロバイダーのスキーマは、公開されている設定ドキュメントに基づいており、このリポジトリではインストール済みの Zed で検証されていません。設定はコマンドで元に戻せるファイルに書き込まれ、ルートがすでに提供されていない限り、何も書き込まれません。

既存のカスタムプロバイダーの認証情報はクライアント内に残り、ユーザー自身のエンドポイントもそのままです。プロキシは設定済みのものの前に挿入され、置き換えることはありません。TOKEN_OPTIMIZER_PROXY=0 はルーティングを無効にし、TOKEN_OPTIMIZER_MODE=off は最適化を無効にします。npm のライフサイクルスクリプトがブロックされる場合があるため、パッケージをインストールしただけでは有効化された証拠にはなりません。 OpenCode のセッションプラグインは、解決済みの設定とプロジェクトディレクトリを使用します。アカウントの認証情報とプロバイダーファイルはそのまま残ります。サポート対象外のエンドポイントとプロバイダーモードでは、ネイティブのルーティングが維持されます。ローカルの管理ポリシーファイルまたは Windows レジストリポリシーで制御される Claude のルーティングも、ネイティブのままです。リモート／MDM ポリシーは起動後に適用されることがあります。ランチャーが報告するのはリスナーの起動だけではなく、実際に観測されたモデルのトラフィックです。 doctor はルーティング設定を確認します。 リクエスト本文のキャプチャは TOKEN_OPTIMIZER_PROXY_CAPTURE でオプトインできます。有効にすると、指定したディレクトリにリクエスト内容が平文で書き込まれます。 キャプチャキューの上限は、リクエスト 128 件、キュー内のスナップショットとメタデータの合計 16 MiB です。上限を超えたキャプチャは警告とともに拒否されますが、リクエストは続行されます。ライブ監査では、不完全なキャプチャ証拠が拒否されます。OOM 修正の再現、メモリ制限下でのリプレイ、残るコスト損失については、割り当ての堅牢化とフォローアップ結果を参照してください。

プロバイダーキーはリクエストヘッダーで転送され、プロキシが読み取ったり、保存したり、書き込んだりすることはありません。これは「機密情報は何も書き込まれない」という主張よりも限定的であり、その違いは重要です。後述のとおり、プロキシは メッセージ内容 をディスクに書き込み、その内容からシークレットを検出することもありません。会話にシークレットが含まれている場合、他のテキストと同様にスピルファイルに書き込まれる可能性があります。

ただし、暗号化されていないネットワークに送信されることはありません。上流が https でもループバックでもない場合は転送せずに拒否します。また、上流が設定されていない場合、プロキシが提供するのは Anthropic 独自のルートのみです。そのため、別のプロバイダー用のクライアントには、キーが誤った会社に送信されるのではなく、プロバイダー名を指定するように伝えます。

**一部のペイロードはディスクに書き込まれます。いつ書き込まれるかを正確に把握しておく必要があります。**省略した内容を参照するには、元に戻る方法を示す必要があります。また、ツールの結果として届いた内容には専用のファイルがないため、その内容は スピルファイル に書き込まれ、マーカーにそのパスが記載されます。これは、エンジンが実際にパスで復元可能なものを省略する場合に限って発生します。たとえば、JSON 配列の末尾、関数本体の集合、文章の一節などです。サイズの下限に満たないリクエスト、どの処理も対象としないリクエスト、そして損失のない省略は、いずれも書き込まれません。

スピルファイルは OS の一時ディレクトリ内の token-optimizer-spill/ に保存されます。内容ごとにファイルが 1 つ作成され、権限は 0600（所有者のみ読み書き可能）に設定されます。ファイル名には、プロキシプロセスごとに新しく生成されるソルトを使った、内容の HMAC が付与されるため、ファイル名から内容が漏れることはなく、実行ごとに名前が重複することもありません。これらのファイルをこちらで読み戻すことはありません。エージェントが、パスをハッシュではなく使う本来の目的で、すでに備えている Read ツールを使って読み取ります。 プロキシの実行中は削除されません。これは意図的なものです。退避データが削除されたマーカーは、この設計がまさに避けようとしている宙に浮いた参照であり、エージェントは書き込まれてから何ターンも後にそのパスをたどる可能性があるためです。そのため、1回の実行中の保持量は、省略する個別のコンテンツによってのみ決まり、上限はありません。頻繁に省略が発生する非常に長いセッションでは、データが蓄積する可能性があります。

プロキシを停止すると、退避ディレクトリは削除されます。各プロキシプロセスは token-optimizer-spill/ の下に専用ディレクトリを持つため、あるプロセスを停止しても、別のプロセスが使用中のパスが削除されることはありません。また、プロキシが停止した時点で、エージェントがそのパスをたどっている可能性もなくなります。強制終了シグナルや停電などにより、クリーンアップされずに実行が終了した場合、ディレクトリは OS の一時ディレクトリに残りますが、手動で安全に削除できます。プロキシを無効にして実行した場合、退避データは一切書き込まれません。

4 つのスイッチと、それぞれがもたらすトレードオフ

オンの 2 つの設定は、7.1.0 まではここでオフと記載されていましたが、これはデフォルトの変更ではなく、リリース済みコードの動作についての誤りでした。値が未設定の場合は常に有効になり、どちらも無効にするには 0、false、no、off のいずれかを設定します。

TOKEN_OPTIMIZER_PROXY_NET_SAVING がオフなのは、ナレッジブロックによってリクエストが大きくなることを想定しているためです。キャッシュへの書き込みとして一度だけ課金された後、セッションの残りでは 0.1 倍で読み込まれるため、長い会話では元が取れますが、短い会話では元が取れません。有効にすると、ナレッジブロックを送信することで上流への送信量がクライアントから受け取ったデータ量を超えるターンでは、そのブロックが削除されます。通信量が増えることはなくなりますが、その代わりにプレフィックスのナレッジを諦めることになります。

ロールアウトチャネル

上記の各スイッチはそれぞれ独立した判断です。10個になるまでは問題ありません。 チャネルなら判断は1つで済みます。stable は今日のデフォルトで有効な機能を示し、 より広い各チャネルには、より狭いチャネルの機能に加えて、現在評価中の機能も すべて含まれます。

beta ではインストールの自己修復が有効になり、canary ではコンパクトなツール定義が 追加されます。この2つは段階的に導入される機能で、チャネルによって有効になります。

より広いチャネルで利用可能になるそれ以外の機能は、すべてリクエストによってのみ有効になり、 チャネルが自動で有効にすることはありません。チャネルが可能にするのは、リクエストだけです。 beta では出力シェーパーと共有ナレッジグラフをリクエストできるようになり、canary では 識別子の置換と思考ブロックの削除が追加され、dev では制限がなくなります。これらは いずれも、モデルが書く内容を変えるか、コードが通常なら実行中のディレクトリから判断する 答えを強制するものです。そのため、暗黙に引き継ぐのではなく、名前を付けて判断する価値があります。

TOKEN_OPTIMIZER_ROLLOUT_CHANNEL=canary TOKEN_OPTIMIZER_FEATURES=substitution

すでに設定している変数は、引き続きチャネルより優先されます。 TOKEN_OPTIMIZER_PROXY_SUBSTITUTE=1 を設定している場合、置換は stable でも有効です。 このスイッチはチャネルができる前にリリースされており、チャネルを切り替えたからといって 独自の設定がひそかに無効になることは想定されていないためです。 TOKEN_OPTIMIZER_DISABLE_FEATURES だけは、どの設定によっても上書きされません。

認識できない名前では何も有効にならず、読み取れない値も「はい」とは扱われません。 どちらの場合も推測せず、報告されます。

npm run doctor           # the channel and what it turned on
npm run doctor -- --features   # every feature and the reason for each

テレメトリーの切り替え

キーはこのリポジトリにはありません。公開されており、パッケージも公開されているため、キーをコミットすると npm view を実行した全員に渡り、すでにインストールされたコピーから取り消すこともできません。そのため、リリースワークフローで tarball にキーを埋め込みます。キーを含まないビルドも引き続き動作し、ローカルでの集計も行います。ただしアップロードはできず、オプトインが機能しているかのように見せないよう、install_doctor は packed without a key と表示します。

lossless について知っておくと便利です。出力から復元できない情報を削除する変換、つまり関数本体、配列の末尾、シグナルの弱い文章をすべて禁止します。一方、空白、null キー、タイムスタンプを列挙した折りたたみ済みの重複行、繰り返されるパスのプレフィックス、リクエスト内に残っているコンテンツへのバックリファレンスなど、復元できる情報は保持します。コードベース探索のワークロードで測定したところ、損失を伴う省略はゼロでありながら、依然として 12.2% を削減します。「モデルがパスを読める」では不十分なレビューや監査作業には、この設定が適しています。

プリセットは出発点であり、上限ではありません。ライブラリでは、プリセットに重ねる CompressionOptions オブジェクトを指定できるため、「アグレッシブに圧縮しつつ、先頭の行を 6 行残す」といった設定が可能です。

キャッシュされたプレフィックス内のグラフ

ここでコストのかかる失敗は、トークンではなくターンです。 このプロジェクトでは、何も削減せず、追加のターンだけでコストが 1.471 倍になった設定を測定しました。そのため、無駄なターンを 1 回防ぐ発見があれば、多くのコンテキスト分のコストをまかなえます。

ナレッジグラフには、そのような無駄を防ぐ情報があります。しかしこれまでは、2 つの方法でモデルに届いており、どちらも遅すぎるかコストが高すぎました。開始時のタスク文から一度だけ選択する SessionStart インデックスと、モデルがすでにアドバイス対象の呼び出しを行うと決めた_後_に発火する PreToolUse の助言です。その助言に従うには、まさに防ぐはずだったターンを消費してしまいます。

検証済みのプロジェクトに関する知見は、デフォルトで キャッシュされたプレフィックス に 2,000 文字の予算で追加されます。プロキシはキャッシュを維持するため、会話中に選択したブロックを固定します。新しいセッションでは、新たに記録された知見を選択できます。Codex Responses API の経路も対象です。共有グラフには、プロジェクト固有の主張は含まれません。注入を無効にするには、TOKEN_OPTIMIZER_PROXY_KNOWLEDGE=0 を設定します。

追加された知識は injectedChars として個別に報告されます。入力トークンが増えるため、コストを正味で改善できるかどうかは、どれだけの作業を防げるかを測定する必要があります。以前の直接比較の結果から、新たに有効になった組み合わせがすべてのワークロードで優位になるとは言えません。

画像

最近まで、画像ブロックはどの処理からも見えていませんでした。すべてのウォーカーが block.text を参照していたためです。画像のコストは約 width * height / 750 トークンなので、1456x816 のスクリーンショット1枚でおよそ1,585トークンになり、その後の各ターンで履歴として再送されます。ブラウザーを操作するエージェントは同じフレームを繰り返し送信しますが、現在はその繰り返しが、リクエスト内にあるコピーへの参照に置き換わります。サイズはファイルヘッダーから取得するため、コーデックへの依存はありません。同じ理由から、リサイズも意図的に行いません。

関連性：デフォルトでは BM25、必要ならモデルも利用可能

保持対象は BM25 でランク付けされます。そのため Python もモデルの重みも不要で、必要な RAM に下限もなく、キャッシュされたプレフィックスをバイト単位で安定させられるほど決定的です。ただし、語彙的な手法には限界があります。「データベースのハンドルが不足した」は「接続プールが枯渇した」とトークンが一致しません。さらに悪いことに、BM25 はその質問で何も返さなくなるのではなく、誤った行を自信を持って選びます。

そこで、改善する方法が2つあります。registerRanker は任意の同期ランカーを登録します。または SemanticEncoder を指定して、プロキシに埋め込みキャッシュをウォームアップさせます。リクエスト単位の非同期プリパスで候補ユニットをまとめて埋め込み、エンジンはこれまでと同様にベクトルを同期的に読み取ります。onnxruntime-node アダプターも含まれており、動的に読み込まれるため、このパッケージがランタイムに依存することはありません。

プリパスで確認されなかったものは、スコアをゼロにするのではなく BM25 にフォールバックします。ベクトルがないのは、こちらの見落としであり、その行についての証拠ではありません。

このアダプターは、モックではなく実際の推論で検証されています。 npm run verify:onnx は、生成スクリプトとともにコミットされた、実際の重みを含む 2.3 KB の ONNX グラフに対して9つのチェックを実行します。これは jest のテストではなくスクリプトです。onnxruntime はネイティブコードで instanceof Float32Array をチェックしますが、jest のスイートごとの VM レルムには独自の型付き配列があるためです。CI ではオプションのランタイムをインストールして実行します。

主張していないこと： 埋め込みモデルがこれらのワークロードで BM25 を実際に上回ること。仕組みは証明されていますが、測定はまだ行われていません。

圧縮は、失うことではなく統合すること

ほかの仕組みでは、すでに_持っていた_ものをチェックポイントに保存して復元します。しかし、それではセッションで最も希少な予算を、すでにコストを払って得たコンテキストの再生に費やします。

ここでの選択はカテゴリの一覧から導き出されるものではなく、cost-to-rederive × irrecoverability × reuse-probability に基づきます。ただし、行き止まりや決定事項には最低限の重みを与えます。見つけるのが安いことと、_もう一度_見つけるのが安いことは同じではないためです。その後の復元は、計測済みの予算内で、問題の途中、コールドレジューム、進行中のいずれかに合わせて調整されます。

どこまで進んだか： クロックスキューは 401 の原因として考えられますか？ 除外済み：トークン署名、クライアント側のクロックドリフト 未検証：サーバー側の NTP スキュー

これは思考の再開です。要約はその記述にすぎません。

質問の内容を把握する段階的な開示

大きなツールの結果は、出力の形式（テストレポート、差分、スタックトレース、ログ、JSON）を解析したうえで、セッションで実際に尋ねられた質問に基づいてプレビューを選びます。先頭にあるというだけで最初の40行を選ぶことはありません。

[selected against: "which shard fails?"]
--- failures ---
  FAILED  DBNetTests.BceOnRelu -- expected 0.0 got NaN
  FAILED  TftGradientFlow -- gradient did not reach the encoder
---- omitted: 1,760 lines of passing tests (expand 8bb6bd66) ----

すべての切り詰めには名前が付いています。何も知らせずに切り詰められた内容について推論するモデルは、何かが欠けていることに気付けないためです。expand はコンテンツアドレス方式のストアから内容を返すので、テストスイートを再実行することはありません。また、展開するたびに次のプレビューが改善され、必要だった内容がグラフに昇格するため、2回目の展開は発生しません。

自分のトランスクリプトから測定するプロンプトキャッシュの経済性

プロバイダーのキャッシュは課金対象であり、プロバイダーごとに異なります。キャッシュヒットは無料の入力トークンではありません。たとえば、Anthropic はキャッシュ読み取りとキャッシュ書き込みで別々の乗数を公開しており、OpenAI と Gemini はそれぞれ独自のキャッシュ入力の使用量と価格ルールを公開しています。Token Optimizer は、クライアントが提供する場合はネイティブのキャッシュフィールドを読み取り、読み取り、書き込み、キャッシュされていない入力、および出力を分けて保持します。あるプロバイダーのキャッシュ乗数を別のクライアントに適用することは決してありません。その後、アトリビューション表示がヒット率にはできない部分を担当します:

! CLAUDE.md:2 has an embedded timestamp, invalidating everything after it
    about 329,421 tokens re-written per session

1 行に帰属され、その_背後_にあるものによって価格が決まります。Keep-warm は、観測されたギャップから得られる期待値によって、TTL ティアごとに決定されます — そしてどちらのティアも支払いに見合わない場合は、そのように伝えます。

タスクの大きさではなく、結果によって決定されるモデルルーティング

誰もがタスクの形から推測し、決して検証しません。これは、各エピソードでどのモデルが実行されたか、そして何が起こったか — リトライ、エラー、ターン数 — を読み取り、両方の誤りに価格を付けます: オーバーパワーなモデルが浪費するものと、アンダーパワーなモデルがリトライで要するコストです。エピソードの半数以上でリトライが必要なティアは、どんな価格でも除外されます。失敗する 4 回の安価なターンは安価ではないからです。

ラチェットになる無駄の検出

レポートは一度読まれて忘れられます。ここでは、検出が永続的で、測定可能で、可逆的な修正 — スキップルール、複合タッチ — を生み出し、さらに約 50 トークンのセッション開始時ブリーフィングを伴うため、無駄が始まることはありません。検出器は、出荷時のフロア_に加えて_、プロジェクト自身の履歴から導出されたパターンであり、それぞれが実際に節約したものを伴っています:

generated/schema.d.ts: read in 9/9 sessions, never the source of a finding
    3,400 tokens/session; cost equivalent not priced; apply: waste_audit action="apply"

あなたのファイルに触れるものはすべて差分として提案され、決して適用されません。

すべてのプロジェクトにわたる 1 つの監査

fleet_audit は、マシン全体を測定されたコストでランク付けし、プロジェクト単位のスキャナーにはできないことを行います: あるプロジェクトで証明された修正が、同じファイル内容を含む他のプロジェクトに提供され、測定された場所からの証拠を伴います。マッチングはファイル名ではなく、コンテンツハッシュによって行われます。

また、他の誰もできない自然実験 — 強制するクライアントと指示するクライアント — を実行し、どちらに転んでもそれを報告し、交絡要因を明記します。

すでに起きた失敗から、オフラインで学習する

すでに支払い済みのすべての失敗したツール呼び出しは、あなたのエージェント自身のトランスクリプトに存在しています。npx token-optimizer-learn はそれらをローカルで読み取り、繰り返し続ける失敗をグループ化し、記憶する価値のあるものを、そのエージェントがすでに読んでいる指示ファイル — Claude Code では CLAUDE.md、Codex では AGENTS.md — に書き込みます。

npx token-optimizer-learn                  # what it found, printed, nothing written
npx token-optimizer-learn --projects       # which projects have transcripts
npx token-optimizer-learn --since 14 --write

--agent <claude|codex|auto>、--project <path>、--since <days>、--max-sessions <n>、--json。--write なしでは何も書き込まれません。また、書き込むブロックは区切り文字で囲まれるため、再度実行すると別のコピーを追記するのではなく、自身のアドバイスを置き換えます — それらのマーカーの外側にあるものは決して触れられません。

次の 3 つのことは行いません。いずれも実際のコーパスで自信過剰に誤ったルールを生み出したためです:

• チェーンされたコマンドラインを責めません。 トランスクリプトにはその行と終了コードが記録されますが、cd X && git grep a && ls b のどれが失敗したかは記録されないため、それらは帰属不能として数えられ、最初のコマンドに押し付けるのではなく数値として報告されます。
• 失敗するビルドをアドバイスに変えません。 失敗するテストやコンパイルは、作業がうまくいっていないことであり、避けるべき習慣ではありません。
• 読み取れなかったものを伝えます。 解析できなかったトランスクリプトと分類できなかった失敗は、件数として出力されます。それらは結果をどこまで信じるべきかの限界を示すからです。

ローカルファイルのみを読み取り — ネットワークなし、アップロードなし — 、推奨テキストが書き込まれる前にホームディレクトリを ~ に短縮します。TOKEN_OPTIMIZER_LEARN_PLUGINS は、別のエージェントのフォーマットを追加するためのモジュール指定子のカンマ区切りリストを受け取ります。あなたが指定しない限り、何も検出またはインポートされません。

信頼性：ツール呼び出しを拒否するフックを提供します

通常の依存関係に求める以上の信頼が必要となるため、次のようにしています。

リリースを検証してください。 npm provenance を使用して CI から公開しています。npm audit signatures により、私たちを信頼しなくても、成果物をワークフローの実行とコミットに結び付けて確認できます。オフラインで検証できるよう、CHECKSUMS.sha256 も同梱しています。

何も起きていないように見える場合は、ライフサイクルバンドルがインストールされていない可能性があります。 MCP サーバーのプロセスは、それを起動したホストを変更できません。また、npm 11 ではライフサイクルスクリプトが allow-scripts によって制限されます。以下に示すクライアント用のネイティブプラグイン／フックバンドルをインストールしてください。MCP サーバーだけを追加した場合、モデルはツールを使えますが、実行前に拒否する機能はありません。レガシーなグローバル Claude Code インストールの復旧は、次の1行で行えます。

npx token-optimizer-install     # wire Claude Code hooks
npx token-optimizer-doctor      # prove the Claude hooks work

ファイルが存在するかではなく、実際に動作するかを確認してください。

npx token-optimizer-doctor      # or npm run doctor, from a clone

これは合成ペイロードを_実際の_フックバイナリに渡し、大きな読み取りが拒否され、小さな読み取りは拒否されないことを検証します。チェックリストなら、このプロジェクトでかつてリリースした、まさにそのバグを見逃していたでしょう。プラグインは接続され、/mcp に表示されていたのに、何も保存されていませんでした。失敗があれば、それぞれに修正方法が示されます。

拒否にはすべて、それぞれの無効化手段が付いています。 無効化手段を隠す強制は、強制です。必要としている人は拒否の対応中であり、README を読んでいるわけではありません。

auth.ts is 91 KB. Call smart_read instead.
(Not what you wanted? TOKEN_OPTIMIZER_MODE=off disables enforcement.)

削除は正確に行われます。 インストーラーは、書き込んだすべてのファイルをハッシュとともに記録します。アンインストール時に削除するのは、内容が一致するファイルだけです。以降に編集したファイルはそのまま残し、名前を示します。独自のフックには一切触れず、settings.json を書き換えることもありません。内容をマージします。

npm run uninstall-hooks              # show the plan; changes nothing
npm run uninstall-hooks -- --apply   # carry it out

直接的な節約と因果グラフの証拠を分けています

この分野のツールはどれも、独自の仮定に基づいて計算した「節約トークン数」を報告しています。その数値を検証するものがないため、誤りだと判定することもできません。

オプティマイザーの結果については、実体化された変更前の状態と、実際にクライアントへ返されたテキストを記録し、関連する展開応答を差し引きます。ネイティブなグラフ置換の反実仮想は、モデルによる推定としてラベル付けし、主要な指標には含めません。

グラフが主張するより広い効果、つまり、知識を提供することで後の再読み込みを防げたかどうかは因果関係に関わるため、ランダム化ホールドアウトを実施します。ファイルごとに層別化したうえで、ファイルへのアクセスの一部では知識の提供を表に出さずに控え、各群の後続の読み取り数の差を効果として測定します。実験で裏付けられるまでは、その効果を合計の純削減量に加えません。画面には、率直に次のように表示されます。

グラフはまだ導入コストを回収できていません

良い知らせしか報告できないツールは、報告しているとは言えません。同じ原則を一貫して適用し、測定できない節約額はゼロではなく不明と表示します。決して $0.00 とは表示しません。「まだ判断できない」を「何も節約できなかった」と表示するのは、見えにくい偽陰性だからです。また、金額は他の人にも伝えられます。

あらゆる環境で動作し、対応ティアを明示します

ティアは好みではなく、プロトコル上の保証です。

• ライフサイクル継続： Claude Code、Codex、GitHub Copilot CLI、Gemini CLI、Qwen Code、Cursor。ネイティブなルーティング／キャプチャ／配信に加え、アクティブモデルによる完了時の振り返りを1回行います。
• ネイティブ監視： Cline、OpenCode、Kilo、Windsurf。ネイティブなルーティング／キャプチャ／配信を行い、意味に基づく書き込みはアクティブモデルが実行します。
• MCP ＋ルール： Roo Code、Zed、Amp、Continue、Crush、Droid。MCP から確認できるアクティビティと明示的なグラフツールを提供しますが、隠れた組み込み呼び出しについては保証しません。

対応するインターフェースはそれぞれ異なります。たとえば、大きな読み取りがモデルに届く前に置き換えられるプロトコルは、それを観察することしかできないプロトコルよりも強いトークン削減保証を提供できます。生成されるレジストリ、アダプター、ダッシュボード、認定レポートはすべて同じ機能情報を参照するため、それぞれの主張が個別に食い違うことはありません。

各クライアントの設定形式は、公開ドキュメントに照らして確認しており、参照元 URL は README に記録されています。

ここにあるものはすべて検証済みで、実行できます

npm run verify:all

これらは飾りではありません。気づかれないまま失敗していたはずのクライアント設定を6件、ユーザーのフックを破壊するインストーラー、強制適用が自身の拒否の半数を検知できなくなる Windows のパスの不具合、そして計画を表示するだけで何も削除しないアンインストーラーを発見しました。

OrcaRouter

OrcaRouter は、1つのエンドポイントを通じて複数のプロバイダーにルーティングする、OpenAI 互換の AI ゲートウェイです。ここではオプティマイザー独自のモデル呼び出し用の正式なプロバイダーとして接続されており、2つの独立した接続方法があります。

どちらも同じ通常の OrcaRouter API キーを生成し、その後の Bearer ヘッダー、エンドポイント、モデルの検出、401 からの復旧は、どちらを使っても同じです。この2つを UI 上で意図的に別々にしているのは、キーを求めることもあればブラウザーを開くこともある単一のボタンでは、ログアウト、再認証、サポート対応が難しくなるためです。

設定方法

ダッシュボード（npm run dashboard）を開いて OrcaRouter カードを使用するか、環境変数で設定します。

export ORCAROUTER_API_KEY=sk-orca-…          # the API-key choice
export TOKEN_OPTIMIZER_ORCA_MODEL=orcarouter/auto   # which model the optimizer calls

アカウントで接続することもできます。この場合、発行されたキーは $TOKEN_OPTIMIZER_HOME（デフォルトは ~/.token-optimizer）に、所有者のみがアクセスできる権限で保存されます。

token-optimizer-route orcarouter --connect   # opens a browser, then stores the key
token-optimizer-route orcarouter --status    # shows a redacted status and the origins in use
token-optimizer-route orcarouter --clear     # removes the stored key

PKCE で発行されるキーは永続的なものであり、リフレッシュトークンではありません。 OrcaRouter が返すのは長期間有効なキーであり、アクセストークンとリフレッシュトークンのペアではありません。そのため、https://www.orcarouter.ai/console/authorized-apps で無効にするまで再利用されます。定期的なリフレッシュは不要で、起動のたびに再認証すると、アカウントの24時間あたり10個というキー発行上限に達してしまいます。リレーが 401 を返すと、拒否されたリクエストを実行したアカウントと認証情報の世代が再認証対象としてマークされ、リフレッシュは試行されません。リフレッシュ可能な OAuth トークンは自動的にローテーションされますが、OrcaRouter のような永続的なキーの付与は、プロバイダーが無効にするまで再利用されます。

起源

認証と推論は異なるホストで行われ、どちらももう一方から派生するものではありません。

https://api.orcarouter.ai/v1/auth/keys は 404 を返します。認証エンドポイントはリレー配下にはありません。セルフホスト環境では、単一の共有オリジンに ORCA_BASE_URL を設定するか、ORCA_AUTH_BASE_URL と ORCA_API_BASE_URL を個別に設定できます。明示的に指定した値が優先され、平文 HTTP が許可されるのはループバックの場合のみです。

モデル

モデルの選択コントロールは、設定されたオリジンで GET /v1/models を実行し、独自のキーを使って作成するリストボックスです。そのため、一覧にはワークスペースから実際に呼び出せるモデルが表示されます。モデル ID の vendor/model 名前空間は維持されます。選択肢はエントリーポイントごとに絞り込まれ、機能を宣言していないモデルは、提示してから拒否するのではなく、提示されません。

• テキストチャット — ?capability=chat を指定し、モデルが openai、anthropic、gemini、openai-response のいずれかのエンドポイントタイプを宣言している必要があります。
• マルチモーダル — 同じ条件に加えて、送信するモダリティに対応する architecture.input_modalities エントリを明示的に宣言している必要があります（宣言されていない機能は許可されません）。
• 埋め込み、画像、動画、リランキング — embeddings、image-generation、openai-video、jina-rerank の各エンドポイントタイプに厳密に一致するモデルが対象です。

検出に失敗した場合は、小規模な検証済みフォールバックリストが表示され、その旨がラベルで示されます（openai/gpt-5.5、anthropic/claude-opus-4.8、google/gemini-3.5-flash、deepseek/deepseek-v4-pro、orcarouter/auto）。コンテキスト、モダリティ、推論負荷のメタデータも保持されます。ライブ取得に成功した場合は、その結果が優先され、フォールバックが混在することはありません。

テキストのエントリーポイント	画像に切り替えた後

2 枚目のキャプチャは、エントリーポイントを画像に切り替えた後の状態です。テキスト専用の選択は解除され、カタログのエントリで画像入力を宣言しているモデルのみが残ります。

npm run evidence:orcarouter を実行すると、カードのスクリーンショットとアサーションが orca-evidence/ に再生成されます（追跡対象外 — 実行時の成果物です）。この README からリンクされているコピーは、ほかのダッシュボードのキャプチャとともに docs/media/orcarouter/ にあります。デリバリーチェックは orca-evidence/ を読み取り、このディレクトリを含むパッチを拒否するため、コミット対象ではなく無視対象になっています。

公正な比較

インストール

すべてのクライアントは同じstdioサーバー（npx -y @ooples/token-optimizer-mcp@latest）を起動しますが、フックで何ができるかはクライアントによって異なり、その違いこそが製品の要です。実行前に拒否できるクライアントでは無駄な呼び出しを拒否できますが、その機能がないクライアントでは通知しかできません。以下では、どちらも正直に記載しています。

16種類すべての設定済み構成は、単一のソースから生成され、npm run verify:clients によって検証される integrations/ にあります。完全な一覧は docs/CLIENT_SUPPORT.md をご覧ください。

すべてのMCP接続では、各クライアントの機能に応じた必須のルーティング指示も、initialize の応答で受け取ります。これにより、すべてのクライアントで常時有効な共通ポリシーが適用されます。ただし、標準のツール実行前インターフェースを備える10種類のクライアントだけが、無駄な組み込み呼び出しを強制的に拒否できます。実際に強制するには、クライアントのライフサイクルバンドルをインストールしてください。

強制モード — 無駄な呼び出しを拒否

以下の10クライアントは、実行前フックを公開しています。パッケージに含まれるライフサイクルバンドルは、機能を考慮した1つの判定エンジンを共有しており、デフォルトは assist です。ルーティング、検索、キャプチャ、収集がすべて有効で、拒否はありません。コストの高い組み込み呼び出しを拒否するには TOKEN_OPTIMIZER_MODE=enforce を設定し、フックを完全に無効にするには off を設定してください。

ルール層 — ホストに拒否 API がない場合の必須ルーティング

Roo Code、Zed、Amp、Continue、Crush、Droid は、組み込み呼び出しを安全に拒否できる、パッケージ化された実行前ブリッジを公開していません。生成される常時有効のルールにより、正確な MCP スキーマを参照できる場合は最適化されたルーティングが必須になり、参照できない場合は範囲を限定したネイティブ操作にフォールバックします。各ホストが記載するパスには、MCP 設定とルールファイルの両方が含まれています。

これらのパスは想定ではなく、実際に検証されています。 各クライアントの公開ドキュメントと照合した結果、正常にインストールされても読み込まれない設定が6つ見つかりました。これには、他のクライアントが使う mcpServers 規約とはスキーマがまったく異なる Kilo も含まれます。規約はスキーマではありません。

Codex

1. MCP サーバーまたはネイティブプラグインを追加する

最適な使用感を得るには、Codex プラグインをインストールしてください。MCP サーバー、トークン最適化スキル、セッションガイダンス、大きな読み取り用フックが含まれています。

codex plugin marketplace add ooples/token-optimizer-mcp
codex plugin add token-optimizer@token-optimizer

/hooks で付属のフックを確認して信頼した後、新しい会話を開始してください。MCP のみをインストールする場合は、次を使用してください。

codex mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

Windows で PowerShell が codex.ps1 シムをブロックする場合は、コマンドランチャーを直接使用してください。

codex.cmd mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

これにより、サーバーが ~/.codex/config.toml に書き込まれます。同じホスト上の Codex CLI、Codex IDE 拡張機能、Codex アプリは、この設定を共有します。

2. インストールを確認する

codex mcp get token-optimizer
codex mcp list

インストール後、新しい Codex の会話を開始して、新しいツールが検出されるようにします。対話型 CLI セッションでは、/mcp で会話に利用できるツールを確認できます。

3. 最適化のガイダンスとフックを追加する

プラグインでは、どちらも自動的に提供されます。MCP のみをインストールする場合は、integrations/AGENTS.md のガイダンスをプロジェクトまたはグローバルの AGENTS.md に追加します。すぐに使える単体のフックも integrations/codex/hooks にあります。その hooks.json を ~/.codex/hooks.json に統合し、スクリプトを ~/.codex/hooks/ にコピーしてから、/hooks で一度確認してください。

Codex のフックは SessionStart でガイダンスを挿入します。TOKEN_OPTIMIZER_MODE=enforce では、同梱の MCP に完全一致する代替手段がある場合、高コストのネイティブ操作をブロックします。これには、cat や Get-Content など、曖昧さのない単一のコードモードのシェル呼び出しも含まれます。複数操作のオーケストレーションは、無関係な作業が破棄されないよう、助言にとどめます。また、MCP が利用できない場合、同じ対象への 2 回目の試行はそのまま実行されます。デフォルトは assist で、取得と記録は行いますが、拒否はしません。TOKEN_OPTIMIZER_MODE=advise では拒否せずにルーティングの助言を追加し、off ではフックを無効にします。AGENTS.md／スキルのガイダンスも引き続き重要です。

より短い指示ブロックを使用する場合は、次のとおりです。

## Token optimization

Use the token-optimizer MCP for large or repeated reads:

- `smart_read` for files over roughly 400 lines and for files already read once.
- `smart_glob`/`smart_grep` for large search results.
- `optimize_text` to store bulky text outside the model context.
- `get_optimization_report` when the user asks for token or compression stats.

Use normal tools for small, one-off operations.

フックの信頼性、マッチング、ツールの対応範囲について詳しくは、最新の Codex フックのドキュメントをご覧ください。

同等の Codex 手動設定

~/.codex/config.toml を自分で編集する場合は、次のとおりです。

[mcp_servers.token-optimizer]
command = "npx"
args = ["-y", "@ooples/token-optimizer-mcp@latest"]

# Optional: keep the cache in a custom location.
# env = { TOKEN_OPTIMIZER_CACHE_DIR = "/absolute/path/to/cache" }

Claude Code

MCP サーバー単体ではなく、プラグインをインストールしてください。 デフォルトで最適化を行うのはプラグインだけです。MCP サーバーを追加しただけでは、モデルが呼び出すかどうかを自由に選べるツール群が提供されるだけです。

/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

インストールはこれで完了です。設定は不要で、有効化するためのフラグもありません。

すぐに利用できる機能

次のセッションの最初のメッセージから、高コストの組み込み呼び出しは拒否され、最適化された同等の操作にリダイレクトされます。

再読み込みのケースは、通常、単独で最も効果が大きく、見落とされることも最も多いものです。セッション中に 5 KB の設定ファイルを 15 回読み込むコストは、200 KB のファイルを 1 回読み込むコストを大きく上回ります。サイズベースのルールでは検出できません。

行き詰まることはありません

いずれもテスト済みの、次の 3 つの特性があります。

• エラー時は処理を許可します。 オプティマイザーでエラーが発生した場合（不正なペイロード、読み取り不能なファイル、予期しない例外など）、プラグインがインストールされていない場合とまったく同じように、元の呼び出しが実行されます。
• ループを防ぎます。 対象ごとに拒否されるのは1 回だけです。再度試すと許可されます。そのため、MCP サーバーがない、または設定に誤りがある場合でも、ファイルごとに無駄なターンが 1 回発生するだけで、自動的に回復し、対応は不要です。
• 低コストの呼び出しには干渉しません。 小さなファイル、ページ単位の読み込み、git log | head、バイナリパスには一切手を加えません。

最適化を無効にする

再インストール不要。変数を1つ変更します。

TOKEN_OPTIMIZER_MODE=advise   # nudge instead of refuse (the pre-5.2 behaviour)
TOKEN_OPTIMIZER_MODE=off      # disable the hooks entirely
TOKEN_OPTIMIZER_LARGE_READ_BYTES=51200   # raise the "large file" threshold

MCP サーバーのみ（非推奨）

最適化の適用なしでツールを使う場合：

claude mcp add --transport stdio --scope user token-optimizer -- \
  npx -y @ooples/token-optimizer-mcp@latest

claude mcp get token-optimizer、または Claude Code 内で /mcp を実行して確認してください。その後、integrations/AGENTS.md の推奨事項を CLAUDE.md に追加します。ただし、コンテキストファイルの指示はあくまで参考情報であり、モデルは日常的にそれを読み飛ばす点にご注意ください。

パッケージをインストールしても、お使いのマシンには何も変更されません。フックと、管理対象の Claude Code、Codex、OpenCode のコマンドは、明示的なコマンドを1つ実行することで設定されます。

npm install -g @ooples/token-optimizer-mcp@latest
token-optimizer-install

token-optimizer-install だけが ~/.claude/settings.json を編集します。インストール自体は書き込み予定のパスを表示して終了します。このフックはマシン上のあらゆるプロジェクトにおけるほぼすべてのツール呼び出しに適用されるため、npm install の副作用として行うべきではありません。元に戻すには token-optimizer-uninstall を実行します。--apply を指定しない限り、ドライランとなります。コンテナイメージやプロビジョニングスクリプトの一部として有効にするには、インストール前に TOKEN_OPTIMIZER_AUTO_INSTALL=1 を設定してください。管理対象の CLI コマンドを有効にするには新しいシェルを開くか、token-optimizer-run を直接使用してください。フックのインストールガイドをご覧ください。

GitHub Copilot CLI

1. MCP サーバーを追加する

現在の Copilot CLI リリースでは、次のようにします。

copilot mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest

お使いの Copilot CLI でまだ copilot mcp が使えない場合は、次の内容を ~/.copilot/mcp-config.json として保存してください。

{
  "mcpServers": {
    "token-optimizer": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@ooples/token-optimizer-mcp@latest"],
      "tools": ["*"]
    }
  }
}

すぐに使えるファイルが integrations/copilot/mcp-config.json にあります。

2. インストールを確認する

copilot mcp get token-optimizer
copilot mcp list

対話型 Copilot セッション内で /mcp show token-optimizer を実行すると、接続状態と利用可能なツールが表示されます。

3. 最適化のガイダンスとフックを追加する

integrations/AGENTS.md をリポジトリの AGENTS.md として使用するか、同じガイダンスを .github/copilot-instructions.md に合わせて記述してください。

ネイティブのライフサイクル統合を行うには、同梱のコマンドでフックをインストールします。このコマンドはエントリーポイントをコピーし、それらの隣に共有コアも配置します。単純な cp -r ではこれを行えません。パッケージに含まれるコアは1つだけで、10個のベンダーコピーは含まれていないためです。

npx -y @ooples/token-optimizer-mcp@latest token-optimizer-install-client --client copilot

既定では .github/hooks/ に書き込みます。--check を指定すると、書き込みは行わず、書き込み予定の内容を報告します。--dest <dir> を指定すると別のディレクトリに書き込みますが、クライアントの設定は変更しません。そのため、クライアント自身の設定が読み込むディレクトリを指定する必要があります。これは、そのディレクトリを実行時に解決するクライアント（Gemini、Qwen、Codex プラグイン）で必須です。

フックは sessionStart で最適化のガイダンスを挿入します。TOKEN_OPTIMIZER_MODE=enforce の場合、大きな組み込み view を拒否し、Copilot が smart_read で再試行するようにします。既定の assist では呼び出しに介入しません。部分読み込みと25 KB未満のファイルは常に変更なく通過します。また、TOKEN_OPTIMIZER_MODE=advise では拒否せずに推奨事項を提示します。リポジトリのフックはユーザーレベルのファイルを上書きせずに動作します。グローバルフックを使う場合は、~/.copilot/hooks/ に配置し、そのディレクトリに合わせてスクリプトパスを変更できます。

フックファイルを変更した後は、Copilot CLI を再起動してください。GitHub の公式ガイド「MCP setup guide」と「hooks reference」をご覧ください。

Gemini CLI

1. MCP サーバーを追加する

ユーザースコープに Token Optimizer を直接追加します。

gemini mcp add --scope user token-optimizer npx -y @ooples/token-optimizer-mcp@latest

または、このリポジトリを Gemini 拡張機能としてインストールすると、MCP の設定と GEMINI.md のガイダンスをまとめて利用できます。

gemini extensions install https://github.com/ooples/token-optimizer-mcp --auto-update

2. インストールを確認する

gemini mcp list
gemini extensions list

Gemini CLI 内で /mcp を実行して接続を確認してください。拡張機能をインストールまたは更新した後は、Gemini CLI を再起動してください。

3. 最適化ガイダンスとフックを追加する

MCP を直接利用する場合は、GEMINI.md をプロジェクトにコピーするか、既存の GEMINI.md にそのルールを統合してください。拡張機能を利用する場合は、このコンテキストファイルとネイティブフックが自動的に追加されます。

拡張機能の SessionStart フックは最適化ガイダンスを注入します。AfterTool フックは、25 KB を超える read_file の全ファイル読み取り結果を検出し、smart_read を提案します。Gemini がこれらの大きな結果をトークンオプティマイザーの末尾呼び出しに自動的に置き換えるようにするには、拡張機能の設定 Automatic large-read routing を true にしてください。

gemini extensions config token-optimizer

自動ルーティングでは、Gemini ネイティブの tailToolCallRequest を使用します。モデルに渡される前に、組み込みの読み取り結果が smart_read の結果に置き換わります。部分読み取りは変更されません。拡張機能のインストール、更新、再設定後は Gemini CLI を再起動してください。公式の Gemini MCP ガイド、拡張機能ガイド、フックのリファレンスをご覧ください。

OpenCode

1. MCP サーバーを追加する

プロジェクト内の opencode.json を作成または更新してください。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "token-optimizer": {
      "type": "local",
      "command": ["npx", "-y", "@ooples/token-optimizer-mcp@latest"],
      "enabled": true
    }
  },
  "instructions": ["./AGENTS.md"]
}

グローバルにインストールする場合は、同じ mcp エントリーを ~/.config/opencode/opencode.json に統合してください。

2. インストールを確認する

opencode mcp list

出力には、設定済みのサーバーとその接続状態が表示されます。

3. 最適化ガイダンスとローカルプラグインを追加する

integrations/AGENTS.md をプロジェクトに AGENTS.md としてコピーしてください。上記の instructions エントリーによって読み込まれます。次に、すぐに使えるローカルプラグインをコピーしてください。

mkdir -p .opencode/plugins
cp integrations/opencode/.opencode/plugins/token-optimizer.js .opencode/plugins/

New-Item -ItemType Directory -Force .opencode/plugins | Out-Null
Copy-Item integrations/opencode/.opencode/plugins/token-optimizer.js .opencode/plugins/

OpenCode 1.3.3 以前（opencode --version で確認できます）では、代わりに integrations/opencode/legacy/.opencode/plugins/token-optimizer.js を同じ場所にコピーしてください。これらのリリースでは、プラグインファイルのすべてのエクスポートがプラグイン関数として呼び出されます。そのため、デフォルトエクスポートが OpenCode 2.x で必要なオブジェクトである現在のファイルは読み込めません。両方のファイル名は同じなので、一方をコピーするともう一方は置き換えられます。

このプラグインは、OpenCode の圧縮プロンプト内に Token Optimizer の使用状態を保持します。TOKEN_OPTIMIZER_MODE=enforce の場合、tool.execute.before フックは 25 KB を超える全ファイル読み取りを拒否し、エージェントを smart_read に誘導します。既定の assist では読み取りが許可されます。小さな読み取りと部分読み取りは常に通常どおり許可され、TOKEN_OPTIMIZER_MODE=advise ではブロックせずにガイダンスを提示します。プラグインを追加した後は OpenCode を再起動してください。公式の OpenCode MCP ガイドとプラグインフックガイドをご覧ください。

汎用 MCP 設定

stdio に対応した MCP クライアントは、次のコマンドで Token Optimizer を起動できます。

{
  "mcpServers": {
    "token-optimizer": {
      "command": "npx",
      "args": ["-y", "@ooples/token-optimizer-mcp@latest"]
    }
  }
}

すぐに使える追加の連携ファイルは、Claude Desktop、Codex、Gemini CLI、OpenCode、GitHub Copilot向けに用意されています。

使い方

通常は、エージェントに自然な言葉で依頼して Token Optimizer を使用します。

Use token-optimizer smart_read for the large server file, then use it again
after the edit so only the diff comes back.

Cache this API response with optimize_text under the key customer-schema,
then retrieve it only if we need the full payload again.

Show my token savings with get_optimization_report.

MCP ツールを直接呼び出せるクライアントでは、基本的な入力は小さな JSON オブジェクトです。

{
  "tool": "smart_read",
  "arguments": {
    "path": "/absolute/path/to/large-file.ts"
  }
}

{
  "tool": "optimize_text",
  "arguments": {
    "text": "A large response, log, document, or generated artifact...",
    "key": "stable-reference-key",
    "quality": 11
  }
}

{
  "tool": "get_optimization_report",
  "arguments": {
    "topN": 10
  }
}

圧縮統計を理解する

optimize_text は呼び出しのたびに測定値を返します。この例では、各フィールドを確認しやすいように意図的に繰り返しの多いペイロードを使用しています。ベンチマークではありません。

{
  "success": true,
  "key": "customer-schema",
  "originalTokens": 4180,
  "compressedTokens": 72,
  "tokensSaved": 4108,
  "percentSaved": 99.55,
  "cached": true,
  "compressionUsed": true
}

get_optimization_report は、ダッシュボードと同じバージョン管理された測定仕様を適用し、条件を満たす操作を次の項目に集計します。

• プレビューの総削減量、関連する展開時の差し引き量、転送量の正味の削減量。
• 観測された返却コンテキストと正味の削減率。
• 追跡された検証済みの操作数。レガシーおよびツールから報告された申告は除外されます。
• アクション／ツール、フックフェーズ、MCP サーバー別の内訳。
• オプションの日付範囲およびセッションのフィルター。

2 つのツールは似ていますが、用途は異なります。

プロンプトを短くすることが目的なら、optimize_text を優先してください。compress_text は、バイト単位の圧縮が特に必要な場合にのみ使用してください。

含まれる機能

ツールの入力と例の詳細については、docs/TOOLS.md を参照してください。

要件とデータ

• Node.js 22 以降
• npm 9 以降
• stdio トランスポートをサポートする MCP クライアント

デフォルトのローカルデータ保存場所は次のとおりです。

• キャッシュ：~/.token-optimizer-cache/
• 分析：~/.token-optimizer-mcp/analytics.db
• セッションと設定：~/.token-optimizer/

キャッシュの保存場所を変更するには、TOKEN_OPTIMIZER_CACHE_DIR を設定してください。

検証し、確認し、削除する

これは、ツール呼び出しを拒否するフックをインストールします。通常の依存関係よりも大きな要求となるため、検証方法と元に戻す方法をすべて記載します。

リリースが正規のものであることを検証します。 パッケージは npm のプロベナンスを使用して CI から公開されます。プロベナンスは、成果物をビルドしたワークフロー実行とコミットに結び付ける証明に署名します。

npm audit signatures

これは、私たちを信頼せずに検証できます。オフライン検証用に、各 GitHub リリースには CHECKSUMS.sha256 が添付されています（sha256sum -c CHECKSUMS.sha256）。ミラーには便利ですが、ハッシュ対象と信頼の基点を共有するため、信頼性は劣ります。

実際に動作することを確認します。 ファイルが配置されているかではなく、実際に 動作する ことを確認します。

npm run doctor

これは合成ペイロードを実際のフックバイナリに渡し、大きな読み取りが拒否され、小さな読み取りは拒否されないこと、セッション開始時にポリシーが出力されること、グラフディレクトリに書き込み可能であること、MCP サーバーが起動してツール一覧を表示することを検証します。失敗した場合は、それぞれに修正方法が示されます。また、install_doctor MCP ツールもあります。

適用をすぐに無効にします。 拒否メッセージには毎回これが表示されるため、ここを探しに戻る必要はありません。

TOKEN_OPTIMIZER_MODE=off      # no enforcement, no hooks
TOKEN_OPTIMIZER_MODE=advise   # suggestions only, nothing is ever denied

削除します。 インストーラーは、書き込んだ各ファイルをハッシュとともに記録するため、最善努力ではなく、正確に削除できます。

npm run uninstall-hooks              # show the plan; changes nothing
npm run uninstall-hooks -- --apply   # carry it out

書き込んだ内容と現在も一致するファイルだけを削除します。その後に編集したものはそのまま残し、名前を示します。削除すれば作業が失われ、黙って削除すればさらに悪いことになるためです。自分で追加したフックはマニフェストに含まれず、変更されることもありません。追加した設定項目は削除できるよう一覧表示します。settings.json を書き換えることはありません。

技術リファレンス

以下の詳細な運用情報は、ツールの全機能、フックのパイプライン、パフォーマンス制御、分析、トラブルシューティングの動作を理解したいユーザー向けに、意図的にそのまま掲載しています。

ツールの完全なリファレンス（合計74個）

コアキャッシュと最適化（8個のツール）

// Cache large content to remove it from context window
optimize_text({
  text: 'Large API response or file content...',
  key: 'api-response-key',
  quality: 11,
});
// Result: 60-90% token reduction

スマートなファイル操作（10個のツール）

// Read a file with automatic caching
smart_read({ path: '/path/to/file.ts' });
// First read: full content
// Subsequent reads: only diff (80% reduction)

// Fetch API with automatic caching
smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
  ttl: 300,
});
// Cached responses: 95% token reduction

ビルドとテストの操作（10 個のツール）

// Run tests with caching
smart_test({
  onlyChanged: true, // Only test changed files
  coverage: true,
});

高度なキャッシュ（10 個のツール）

// Configure multi-tier cache
smart_cache({
  operation: 'configure',
  evictionStrategy: 'LRU',
  l1MaxSize: 1000,
  l2MaxSize: 10000,
});

監視とダッシュボード（7 個のツール）

// Create an alert
alert_manager({
  operation: 'create-alert',
  alertName: 'high-cpu-usage',
  channels: ['slack', 'email'],
  threshold: { type: 'above', value: 80 },
});

// View session token usage
get_session_stats({});
// Result: Detailed breakdown of token usage by tool

インテリジェンスと要約（6 個のツール）

トークン分析（5 個のツール）

コンテキストの状態とストレージ（2 個のツール）

アーキテクチャとグローバルフック

ネイティブクライアントのライフサイクル対応

MCP サーバーはどのクライアントでも同一ですが、ライフサイクル API は同一ではありません。リポジトリは、Claude のイベント名をツールにコピーして暗黙に無視されるようにするのではなく、クライアントネイティブのアダプターを提供しています。

デフォルトは assist です。ルーティング、取得、キャプチャ、ハーベストが有効で、何も拒否されません。これは 2 つの独立したハーネスが当社の最良の構成として測定した姿勢です -- THOL では、assist は 14.4 ターンで 0.971 を記録し、対照の 16.2 ターンで 0.969 を上回りました。一方、enforce は 20.3 ターンで 0.960 を記録し、タスクあたり対照の 1.471 倍のコストがかかりました（17 タスクの中央値、より安価だったのはそのうち 2 タスクのみ）。上記の拒否を有効にするには TOKEN_OPTIMIZER_MODE=enforce を設定します。これは 25,600 バイトのしきい値を使用します。TOKEN_OPTIMIZER_LARGE_READ_BYTES で上書きするか、拒否を伴わないルーティング勧告には TOKEN_OPTIMIZER_MODE=advise を、ライフサイクル統合を無効にするには TOKEN_OPTIMIZER_MODE=off を使用します。部分的な読み取りは常に通過します。これはすでに完全なキャッシュ読み取りよりも効率的である可能性があるためです。また enforce では、失敗した MCP サーバーが作業を恒久的にブロックしないよう、1 回の繰り返し試行が許可されます。

分析ワークフローとストレージ

// Get per-hook analytics
get_hook_analytics({
  startDate: '2025-01-01T00:00:00Z',
  endDate: '2025-12-31T23:59:59Z',
});
// Result: Shows which hooks consume the most tokens

// Get per-action analytics
get_action_analytics({});
// Result: Shows which tools use the most tokens

// Export analytics as CSV
export_analytics({
  format: 'csv',
  hookPhase: 'PreToolUse',
});
// Result: CSV export filtered by PreToolUse hook

グローバルフックシステム（7 フェーズ最適化）

この完全な 7 フェーズパイプラインは、任意の Claude Code グローバルフックインストールに適用されます。Codex、Copilot、Gemini、OpenCode は、イベント名、ペイロード、結果置換機能が異なるため、上記のより小規模なネイティブアダプターを使用します。

グローバルフックがインストールされている場合、token-optimizer-mcp はすべてのツール呼び出しで自動的に実行されます：

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: PreToolUse - Tool Replacement                      │
│ ├─ Read   → smart_read   (80% token reduction)             │
│ ├─ Grep   → smart_grep   (80% token reduction)             │
│ └─ Glob   → smart_glob   (75% token reduction)             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Input Validation - Cache Lookups                   │
│ └─ get_cached checks if operation was already done          │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: PostToolUse - Output Optimization                  │
│ ├─ optimize_text for large outputs                          │
│ └─ compress_text for repeated content                       │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 4: Session Tracking                                   │
│ └─ Log all operations to operations-{sessionId}.csv         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 5: UserPromptSubmit - Prompt Optimization             │
│ └─ Optimize user prompts before sending to API              │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 6: PreCompact - Pre-Compaction Optimization           │
│ └─ Optimize before Claude Code compacts the conversation    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 7: Metrics & Reporting                                │
│ └─ Track token reduction metrics and generate reports       │
└─────────────────────────────────────────────────────────────┘

パフォーマンスの根拠

ツールの説明に記載された削減目標は設計上の目標であり、本番環境での測定値ではありません。これらが検証済み台帳に記録されることはありません。リクエスト単位の測定値を確認するにはダッシュボードまたは get_optimization_report を使用し、対象となる行と除外された行の両方を確認するには npm run dashboard:audit-savings を実行してください。普遍的な金額は提示していません。有効なレートを設定するのは、ご自身のプロバイダー、モデル、キャッシュ、ルート、プラン、ティア、クレジットを反映している場合に限ってください。

使用例

基本的なキャッシュ

// Cache large content to remove from context window
const result = await optimize_text({
  text: 'Large API response or file content...',
  key: 'cache-key',
  quality: 11,
});
// Result: Original tokens removed, only cache key remains (~50 tokens)

// Retrieve later
const cached = await get_cached({ key: 'cache-key' });
// Result: Full original content restored

スマートなファイル読み取り

// First read: full content
await smart_read({ path: '/src/app.ts' });

// Subsequent reads: only changes (80% reduction)
await smart_read({ path: '/src/app.ts' });

API キャッシュ

// First request: fetch and cache
await smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
  ttl: 300,
});

// Subsequent requests: cached (95% reduction)
await smart_api_fetch({
  method: 'GET',
  url: 'https://api.example.com/data',
});

セッション分析

// View token usage for current session
await get_session_stats({});
// Result: Breakdown by tool, operation, and savings

// Analyze entire project
await analyze_project_tokens({
  projectPath: '/path/to/project',
});
// Result: Cost estimation and optimization opportunities

技術スタック

• ランタイム：Node.js 22+
• 言語：TypeScript
• データベース：SQLite (better-sqlite3)
• トークン計測：tiktoken (GPT-4 tokenizer)
• 圧縮：Brotli (built-in Node.js)
• キャッシュ：マルチティア LRU/LFU/FIFO キャッシュ
• プロトコル：MCP SDK (@modelcontextprotocol/sdk)

対応する AI ツール

Token Optimizer は stdio 対応の MCP クライアントで動作し、以下のツール向けに公式のセットアップガイドを用意しています。

• OpenAI Codex - MCP の直接セットアップ、または同梱のプラグイン、スキル、フック
• Claude Code - MCP の直接セットアップ、または同梱のプラグイン、スキル、フック
• GitHub Copilot CLI - MCP 設定、AGENTS.md のガイダンス、リポジトリフック
• Google Gemini CLI - MCP の直接セットアップ、または同梱のコンテキストとフックの拡張機能
• OpenCode - ローカル MCP 設定、AGENTS.md の手順、コンパクションプラグイン
• Claude Desktop、Cursor、Cline、Windsurf - 標準の MCP JSON 設定

対応するコマンドと設定ファイルについては、インストールを参照してください。

パフォーマンス特性

• 圧縮率：通常 2～4 倍（繰り返しの多いコンテンツでは最大 82 倍）
• コンテキストウィンドウの削減率：すべての操作で平均 60～90％
• キャッシュヒット率：一般的な使用で 80％超
• 操作のオーバーヘッド：キャッシュ操作で 10ms 未満（50～70ms から最適化）
• 圧縮速度：テキスト 1 KB あたり約 1ms
• フックのオーバーヘッド：操作あたり 10ms 未満（メモリ内最適化により 7 倍改善）

パフォーマンスの最適化

PowerShell フックは、次の方法によりオーバーヘッドを 50～70ms から 10ms 未満に削減するよう最適化されています。

• メモリ内のセッション状態：各操作でディスク I/O を行う代わりに、セッションデータをメモリ内に保持します
• ログ書き込みのバッチ処理：操作ログをバッファーに格納し、5 秒ごと、または 100 操作ごとにフラッシュします
• 遅延永続化：ディスクへの書き込みは必要な場合（セッション終了、最適化、レポート）にのみ行われます

環境変数

以下の環境変数でフックの動作を制御できます。

MCP サーバーはデフォルトで19個のツールからなるコアカタログを公開し、ツールのスキーマがモデルのコンテキストを大きく占有しないようにします。サーバーの起動前に TOKEN_OPTIMIZER_TOOL_PROFILE=full を設定すると、104個すべての特化ツールが公開されます。TOKEN_OPTIMIZER_TOOL_PROFILE=core はデフォルトを明示的に指定する形式です。ライブグラフの取得では TOKEN_OPTIMIZER_TOOL_PROFILE=continuity を使用し、取得とクエリのみを公開します。拡張された cognitive プロファイルでは、チェックポイント、結果、レシートの証明が追加されます。ネイティブトークン監査では、continuity が起動時に480トークン、拡張 cognitive が694トークン、core が4,815トークン、full が30,125トークンを使用すると測定されています。ステートフルなコンシューマーには、通常MCPツールは0個しか提供されません。ホストのアクション前配信では、クライアントのライフサイクルチャネルを通じて、選択されたカプセルのみが追加されます。有効化されている他のMCPサーバーは、それぞれ独立して独自のスキーマを追加します。

ファイル中心の作業では、TOKEN_OPTIMIZER_TOOL_PROFILE=files を有効にすると、smart_read、smart_write、smart_edit、smart_glob、smart_grep、get_cached、expand の7つのツールが公開されます。このプロファイルでは、ファイルとキャッシュからの取得機能を維持しつつ、wiki、監査、セッションの各ツールを除外します。圧縮プロキシと併用できます。full-files 構成と測定済みのトレードオフについては、ライブ比較ランナーを参照してください。

現行の強化版クロスCLIスモークテストは、適格とは判定されていません。最終的なCodexからClaudeへの敵対的ペアでは、後続の両方が正しく、実行時のカプセルも正確なプロバイダーモデルの証明とMCPツール数0で配信されましたが、実行時のトークン使用量は5.383％増加し、レイテンシは41.758％増加しました。逆方向の実行時テストはClaudeのプロバイダークォータによって阻止され、Antigravity 1.1.11ではGeminiモデルの実行前にアカウント認証が必要でした。これらの署名付き結果により、リリース判定は insufficient のままです。これは来歴が正しく機能し、フェイルクローズ動作が機能している証拠であり、有効性が十分に検証されたことや、あらゆる条件で優位であることを示すものではありません。

置き換えに適したプロトコルは、このスモークテストより意図的に大規模です。全ファミリー・全アームを対象とした試行エンベロープが54,054件、プロバイダー呼び出しが113,022件、独立したモデルファミリーが3つ、方向別の非劣性評価が含まれます。また、方向ごと・アームごとに1,056件のハードネガティブ機会を設け、点推定値だけでなく、ボンフェローニ補正後の95％ファミリーワイズ誤配信上限も1％未満に保つ必要があります。固定済みの指標カバレッジを検証するには、 npm run verify:ucr:study-design を実行してください。完全なプロトコルとCLIドライバーの仕様は、 evals/ucr/FULL_STUDY_CONTRACT.md に記載されています。

パフォーマンス制御

• TOKEN_OPTIMIZER_USE_FILE_SESSION（デフォルト：false）

  • true に設定すると、ファイルベースのセッション追跡に戻ります（レガシーモード）
  • メモリ内のセッション状態で問題が発生した場合に使用します
  • 例：$env:TOKEN_OPTIMIZER_USE_FILE_SESSION = "true"

• TOKEN_OPTIMIZER_SYNC_LOG_WRITES（デフォルト：false）

  • true に設定すると、ログのバッチ書き込みを無効にします
  • ディスクへの書き込みを即時に行います（速度は低下しますが、より堅牢です）
  • デバッグ時や、ログが失われる場合に使用します
  • 例：$env:TOKEN_OPTIMIZER_SYNC_LOG_WRITES = "true"

• TOKEN_OPTIMIZER_DEBUG_LOGGING（デフォルト：true）

  • false に設定すると、DEBUGレベルのログ記録を無効にします
  • ログファイルのサイズを削減し、パフォーマンスを向上させます
  • INFO／WARN／ERRORログは引き続き記録されます
  • 例：$env:TOKEN_OPTIMIZER_DEBUG_LOGGING = "false"

開発パス

• TOKEN_OPTIMIZER_DEV_PATH
  • ローカルの開発用インストール先のパス
  • 指定されていない場合は ~/source/repos/token-optimizer-mcp に自動設定されます
  • 任意の開発パスを指定するには、この値を上書きします
  • 例：$env:TOKEN_OPTIMIZER_DEV_PATH = "C:\dev\token-optimizer-mcp"

パフォーマンスへの影響：デフォルトのメモリ内モードを使用すると、フックのオーバーヘッドが7倍改善します。

• 変更前：フック操作あたり50～70ms
• 変更後：フック操作あたり<10ms
• フックのレイテンシを85％削減

トークン削減量のモニタリング

リアルタイムのセッション監視

実際のトークン削減量を確認するには、get_session_stats ツールを使用します。

// View current session statistics with token savings breakdown
await get_session_stats({});

出力に含まれる内容：

• トークンの合計削減量（実際の削減量です！）
• トークン削減率（例：「60% 削減」）
• キャッシュヒット率と圧縮率
• ツール別の内訳（Read、Grep、Glob など）
• 最適化効果が高い操作の上位 10 件（最適化前後の比較）

出力例：

{
  "sessionId": "abc-123",
  "totalTokensSaved": 125430, // ← THIS is your savings!
  "tokenReductionPercent": 68.2,
  "originalTokens": 184000,
  "optimizedTokens": 58570,
  "cacheHitRate": 72.0,
  "byTool": {
    "smart_read": { "saved": 45000, "percent": 80 },
    "smart_grep": { "saved": 32000, "percent": 75 }
  }
}

セッション追跡ファイル

すべての操作は、セッションデータファイルに自動的に記録されます。

場所：~/.claude-global/hooks/data/current-session.txt

形式：

{
  "sessionId": "abc-123",
  "sessionStart": "20251031-082211",
  "totalOperations": 1250, // ← Number of operations
  "totalTokens": 184000, // ← Cumulative token COUNT
  "lastOptimized": 1698765432,
  "savings": {
    // ← Auto-updated every 10 operations (Issue #113)
    "totalTokensSaved": 125430, // Tokens saved by compression
    "tokenReductionPercent": 68.2, // Percentage of tokens saved
    "originalTokens": 184000, // Original token count before optimization
    "optimizedTokens": 58570, // Token count after optimization
    "cacheHitRate": 42.5, // Cache hit rate percentage
    "compressionRatio": 0.32, // Compression efficiency (lower is better)
    "lastUpdated": "20251031-092500" // Last savings update timestamp
  }
}

v1.x の新機能：savings オブジェクトが 10 回の操作ごとに自動更新されるようになり、リアルタイム監視のために get_session_stats() を手動で呼び出す必要がなくなりました。これにより、トークン最適化のパフォーマンスをすぐに確認できます。

仕組み：

• 10 回の操作ごとに、PowerShell フックが get_cache_stats() MCP ツールを自動的に呼び出します
• キャッシュのパフォーマンスデータ（圧縮率、圧縮前後のサイズ）から削減指標が計算されます
• セッションファイルは、最新の削減データでアトミックに更新されます
• MCP 呼び出しに失敗した場合、操作を妨げることなく更新がスキップされます

注記：操作ごとの詳細な分析には、get_session_stats() を使用してください。セッションファイルでは、集計された高レベルの指標を確認できます。

プロジェクト全体の分析

プロジェクト全体のトークン使用量を分析します。

// Analyze project token costs
await analyze_project_tokens({
  projectPath: '/path/to/project',
});

確認できる内容：

• トークン総コストの推定値
• トークン数が多いファイル
• 最適化の機会
• 現在の API 料金に基づくコスト予測

キャッシュのパフォーマンス

キャッシュヒット率とストレージ効率を監視します。

// View cache statistics
await get_cache_stats({});

指標：

• エントリの合計数
• キャッシュヒット率（%）
• 平均圧縮率
• ストレージの合計削減量
• アクセス頻度の高いキー

トラブルシューティング

CLI 接続と検出

Codex にツールが表示されない

1. codex mcp get token-optimizer を実行します。
2. codex mcp list でエントリが有効になっていることを確認します。
3. 新しい Codex 会話を開始します。
4. 対話型 CLI で /mcp を実行し、サーバーのステータスを確認します。

Windows で codex がブロックされる

制限の厳しい実行ポリシーでは、PowerShell が codex.ps1 シムの実行を拒否する場合があります。インストールと確認のコマンドでは codex.cmd を使用するか、ユーザー範囲の PowerShell 実行ポリシーを確認してください。

Codex から Token Optimizer を削除する

codex mcp remove token-optimizer

これにより Codex の登録は削除されますが、ローカルのキャッシュや分析データベースは削除されません。

よくある問題と解決方法

問題：「Invalid or malformed JSON」が Claude Code Settings に表示される

症状：install-hooks の実行後、Claude Code に「Invalid Settings」エラーが表示される

原因：settings.json ファイルに UTF-8 BOM（バイトオーダーマーク）が追加されている

解決方法：BOM の問題が修正された v3.0.2 以降にアップグレードします。

npm install -g @ooples/token-optimizer-mcp@latest

すでに v3.0.2 以降を使用している場合は、BOM を手動で削除します。

# Windows: Remove BOM from settings.json
$content = Get-Content "~/.claude/settings.json" -Raw
$content = $content -replace '^\xEF\xBB\xBF', ''
$content | Set-Content "~/.claude/settings.json" -Encoding utf8NoBOM

# Linux: Remove BOM from settings.json
sed -i '1s/^\xEF\xBB\xBF//' ~/.claude/settings.json

# macOS: Remove BOM from settings.json (BSD sed requires empty string after -i)
sed -i '' '1s/^\xef\xbb\xbf//' ~/.claude/settings.json

問題：インストール後にフックが機能しない

症状：トークン最適化が自動で行われない

診断：

1. フックがインストールされているか確認します。

   # Windows
   Get-Content ~/.claude/settings.json | ConvertFrom-Json | Select-Object -ExpandProperty hooks
   

   # macOS/Linux
   cat ~/.claude/settings.json | jq .hooks
   

2. dispatcher.ps1 が存在することを確認します。

   # Windows
   Test-Path ~/.claude-global/hooks/dispatcher.ps1
   

   # macOS/Linux
   [ -f ~/.claude-global/hooks/dispatcher.sh ] && echo "Exists" || echo "Missing"
   

解決方法：インストーラーを再実行します。

# Windows
powershell -ExecutionPolicy Bypass -File install-hooks.ps1

# macOS/Linux
bash install-hooks.sh

問題：キャッシュヒット率が低い（<50%）

症状：セッション統計に表示されるキャッシュヒット率が 50% 未満

原因：

1. 多数の新しいファイルを扱っている（想定どおり）
2. キャッシュが最近クリアされた
3. TTL（有効期間）が短すぎる

解決方法：

1. 作業を開始する前にキャッシュをウォームアップします。

   await cache_warmup({
     paths: ['/path/to/frequently/used/files'],
     recursive: true,
   });
   

2. 安定した API ではTTL を延長します。

   await smart_api_fetch({
     url: 'https://api.example.com/data',
     ttl: 3600, // 1 hour instead of default 5 minutes
   });
   

3. キャッシュサイズの上限を確認します。

   await smart_cache({
     operation: 'configure',
     l1MaxSize: 2000, // Increase from default 1000
     l2MaxSize: 20000, // Increase from default 10000
   });
   

問題：メモリ使用量が多い

症状：Node.js プロセスが過剰なメモリを使用している

原因：メモリ内のキャッシュが大きい（L1/L2 階層）

解決方法：キャッシュの上限を設定します。

await smart_cache({
  operation: 'configure',
  evictionStrategy: 'LRU', // Least Recently Used
  l1MaxSize: 500, // Reduce L1 cache
  l2MaxSize: 5000, // Reduce L2 cache
});

または、キャッシュをクリアします。

await clear_cache({});

課題：初回操作が遅い

症状：最初の Read／Grep／Glob 操作が遅い

原因：キャッシュが空で、インデックスを構築しています

解決策：想定どおりの動作です。2 回目以降の操作は 80～90％高速になります。

キャッシュを事前にウォームアップするには：

await cache_warmup({
  paths: ['/src', '/tests', '/docs'],
  recursive: true,
  schedule: 'startup', // Auto-warm on every session start
});

課題：Windows で「Permission denied」エラーが発生する

症状：キャッシュファイルまたはログファイルに書き込めない

原因：PowerShell の実行ポリシーまたはファイルのアクセス許可

解決策：

1. 実行ポリシーを設定します：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. ファイルのアクセス許可を確認します：

   icacls "$env:USERPROFILE\.token-optimizer"
   

3. 必要に応じて、インストーラーを管理者として再実行します

課題：キャッシュファイルが大きくなりすぎる

症状：~/.token-optimizer/cache.db が 1GB を超えている

原因：非常に大きなファイルや多数の API レスポンスをキャッシュしています

解決策：

1. 古いエントリーを削除します：

   await clear_cache({ olderThan: 7 }); // Clear entries older than 7 days
   

2. キャッシュの保持期間を短くします：

   await smart_cache({
     operation: 'configure',
     defaultTTL: 3600, // 1 hour instead of 7 days
   });
   

3. キャッシュを手動で削除します（最終手段）：

   rm -rf ~/.token-optimizer/cache.db
   

ヘルプの利用

ここで取り上げていない問題が発生した場合：

1. フックのログを確認します：~/.claude-global/hooks/logs/dispatcher.log
2. セッションデータを確認します：~/.claude-global/hooks/data/current-session.txt
3. 問題を報告します：GitHub Issues
   • デバッグログを含めてください
   • OS と Node.js のバージョンを含めてください
   • get_session_stats の出力を含めてください

制限事項

• 短いテキスト：500 文字を超える内容に最適です（短い断片ではキャッシュのオーバーヘッドが発生します）
• 一度限りの内容：再度参照されない内容には効果がありません
• キャッシュストレージ：ディスク使用量の問題を防ぐため、7 日後に自動でクリーンアップされます
• トークン数の計算：GPT-4 のトークナイザーを使用します（Claude では概算ですが、十分に近い値です）

開発

git clone https://github.com/ooples/token-optimizer-mcp.git
cd token-optimizer-mcp
npm ci
npm run build
npm test
node scripts/mcp-smoke.mjs

開発中に Codex でローカルビルドを使用するには：

codex mcp add token-optimizer-local -- node /absolute/path/to/token-optimizer-mcp/dist/server/index.js

ドキュメント

• クイックスタート
• ツールリファレンス
• Codex とエージェント向けガイダンス
• フックのインストール
• テスト
• コントリビューション
• セキュリティポリシー
• 変更履歴

ライセンス

MIT ライセンス - 詳細は LICENSE をご覧ください

作者

ooples チームが、サポート対象のコーディングエージェント全体でトークン効率を測定可能な形で高めるために開発しました。