tokentrust

インストール

TokenTrust は、同等に重要な補完関係にある 2 種類のディストリビューションとして提供されます。Node.js ツールチェーン向けの npm パッケージと、Python ツールチェーン向けの PyPI パッケージです。どちらも同じ CLI インターフェース、同じ TT01～TT05 の検証カテゴリ、同じバンドル済みタスクコーパスを備えた tokentrust コマンドをインストールします。既存のスタックに合う方を選んでください。

npm（Node.js）：

npx tokentrust-cli verify --proxy rtk

クローンもローカルビルドも不要です。npx が公開済みパッケージを取得して、そのまま実行します。依存関係としてインストールする場合は、npm install -g tokentrust-cli を実行してください。

pip（Python）：

pip install tokentrust-cli
tokentrust verify --proxy rtk

Python パッケージの詳しいドキュメントは、python/README.md をご覧ください。npm パッケージの js-tiktoken 依存関係ではトークナイザーデータが同梱され、完全にオフラインで使用できる一方、Python パッケージの tiktoken 依存関係では、同じ公開データが初回使用時に取得・キャッシュされるという、両者の実際の動作上の違いについても説明しています。

このリポジトリにバンドルされたタスクコーパスに対して、上記のコマンドを実行した際の実際の出力です。

$ npx tokentrust-cli verify --proxy rtk

TokenTrust v0.1 -- Token/Context-Reduction Claims Verification
Proxy: rtk 0.43.0 | Repo: TokenTrust | Task corpus: 23 labeled tasks

[MEASURED] TT01 Compression Ratio
  Claimed (rtk README): up to 70% context reduction
  Measured (this repo, this corpus): 60.6% average reduction across 23 tasks
  Range: 0.0% ("verify-go-build-filter") to 95.4% ("verify-git-log-filter")

[MEASURED] TT02 Cost-Savings Delta
  Baseline (uncompressed): $0.02 across 23 tasks @ claude-5-sonnet pricing
  Compressed (rtk-proxied): $0.00 across 23 tasks
  Actual savings: 77.0% ($0.01) -- vs. claimed 70% ceiling

[FAIL]  TT03 Never-Worse Output Guard
  2/23 tasks regressed in task-completion diff vs. uncompressed baseline

[PASS]  TT05 Version-Drift Regression Check
  No prior verified baseline for rtk on this repo -- this run establishes the first baseline.

Summary: 77.0% measured cost savings (claimed: up to 70%) -- see full report

これは実際の実行結果であり、手入力した例ではありません。npx tokentrust-cli は同じ dist/cli.js エントリーポイントを呼び出すため（tokentrust というコマンド名は変わりません）、クローンせずにお使いのマシンで同じ結果を再現できます。

測定内容

• TT01：圧縮率。 ローカルのトークナイザー（js-tiktoken）を使用して、コーパス内のすべてのタスクを対象に、実際のトークン削減量を測定します。
• TT02：コスト削減差分。 公開されているモデルの料金に基づき、TT01 で測定したトークン差分から金額ベースのコスト削減量を算出します。オプションの --live モードでは、実際にプロバイダーへの課金が発生するサンプルを使って推定値を検証します（オプトイン方式で、ご自身の API キーが必要です。--confirm-cost による確認が必要で、デフォルトでは最大 5 件のタスクに制限されます）。
• TT03：出力が悪化しないためのガード。 タスクが圧縮後も必須として指定した内容が、プロキシの圧縮出力から削除されていないかを確認します。
• TT04：ツール間の比較ベンチマーク。 --proxy を複数回指定すると、TokenTrust は同一のタスクコーパスを各プロキシに通し、並べて比較します。
• TT05：バージョン差異による回帰検出。 実行結果の測定済み削減量を、同じプロキシとリポジトリの組み合わせで最後に検証されたベースラインと比較します。これにより、バージョン更新に伴う気付かれにくい回帰（rtk#582 など）を自動的に検出します。

コマンド

tokentrust verify --proxy <name> [options]

フラグ	説明
--proxy <name>	検証するプロキシです。複数回指定できます。TT04 のツール横断比較を実行するには、複数回指定してください。対応している値：rtk、headroom。必須です。
--repo <path>	測定対象のリポジトリです。デフォルトは現在のディレクトリです。
--tasks <file>	タスクコーパスの YAML ファイルです。デフォルトは同梱の 23 タスクコーパスです。
--live	料金表から推定する代わりに、最初のプロキシについてプロバイダーに課金される実トークン数をサンプリングします。--confirm-cost が必要です。
--confirm-cost	実際の API 呼び出しを行う前に、--live が表示する推定費用を確認します。
--live-max-tasks <n>	--live モードでサンプリングするタスクの最大数です。デフォルトは 5 です。
--format <terminal|json>	レポートの出力形式です。デフォルトは terminal です。
-h、--help	ヘルプメッセージを表示して終了します。

この表（および下記の tokentrust mcp リファレンス）は、古いコピーではなく、公開済みの tokentrust-cli パッケージの実際の --help 出力と照合済みです。実際の --help テキストと 上の表との既知の差異は、見過ごして繰り返すのではなく、FAQ で明示しています。

--format json を指定すると、各カテゴリの申告値と測定値が構造化データとして出力されるため、 スクリプトやエージェントはターミナルのテキストを解析せずに、jq で比較結果を直接取り出せます。

ゲート対象の失敗がなく実行が完了すると終了コードは 0 になり、それ以外の場合は 0 以外になります。同梱の GitHub Action の --fail-on-regression はこの値をそのまま失敗した CI ステップに対応付けるため、バージョンのずれによる リグレッションが発生すると、気付かないままリリースされるのではなく、ビルドが失敗します。

同梱の GitHub Action（action/action.yml）を使って CI に追加すると、プロキシのバージョンが更新されるたびに 検証が自動で再実行されます。

- uses: RudrenduPaul/TokenTrust-CLI@main
  with:
    proxy: rtk
    fail-on-regression: 'true'
    cli-version: '<pin to the exact tokentrust-cli version you have verified against>'

Action のデフォルトに頼らず、cli-version を明示的に固定してください。この入力では Action は意図的に latest をサポートしていません。バージョンの固定はサプライチェーンを保護するための対策です。これにより、 侵害された npm パッケージの公開が、意図的なバージョン更新なしに、次回の実行でこの Action を使うすべての ワークフローに及ぶことを防げます。この入力に対する Action 自体のデフォルトは、TT04／TT05／MCP より前の初期リリースです。 cli-version を省略すると、この README に記載されたバージョンではなく、その古いバージョンが実行されます。

エージェントネイティブ／MCP

TokenTrust は、Semgrep、Trivy、Snyk、SonarQube と同じ、CLI と MCP サーバーを組み合わせたモードで提供されます。 つまり、1 つのバイナリ、1 つの基盤となる検証エンジンに加え、シェルではなく MCP（Model Context Protocol） を話すエージェント向けの、薄い第 2 の入り口を備えています。 tokentrust mcp は stdio 経由で MCP サーバーを起動し、verify_proxy_savings という単一のツールを公開します。 このツールは tokentrust verify が使用するものと同じ runVerify() エンジンを直接呼び出します。検証ロジックは重複せず、 このツールは --format json がすでに出力するものとまったく同じ構造化 JSON レポートを返します。

npx tokentrust-cli mcp

MCP クライアントに登録する

クライアントのサーバー設定で、mcp 引数を指定してこのバイナリを参照します。Claude Code、 Claude Desktop、または mcpServers ブロックを読み込むその他のクライアントの場合：

{
  "mcpServers": {
    "tokentrust": {
      "command": "npx",
      "args": ["tokentrust-cli", "mcp"]
    }
  }
}

ツール

フィールド	説明
verify_proxy_savings	ツール名です。verify のフラグを --format を除いて1対1で反映します。MCP 呼び出しは常に機械向けであるため、このツールは常に構造化 JSON レポートを返します。
proxy（必須）	単一のプロキシ名（"rtk"）または配列（["rtk", "headroom"]）を指定すると、1回の呼び出しで TT04 のツール横断比較を実行します。対応している値：rtk、headroom。
repo	--repo と同じです。既定値は MCP サーバープロセスの現在の作業ディレクトリです。
tasks	--tasks と同じです。既定値は同梱のタスクコーパスです。
live / confirmCost	CLI と同じ --live / --confirm-cost 安全ゲートです。同じ呼び出しで両方が明示的に true に設定されない限り、プロバイダーへの課金が発生するライブ API 呼び出しは行われません。どちらの既定値も true ではありません。
liveMaxTasks	--live-max-tasks と同じです。既定値は 5 です。

これは、稼働中の tokentrust mcp サーバーから取得した、ツールの実際の未編集の tools/list スキーマです（簡潔にするため、ここでは各フィールドの説明を省略しています。稼働中のサーバーはそれらをすべて返します）。

{
  "name": "verify_proxy_savings",
  "title": "Verify proxy token/cost savings",
  "inputSchema": {
    "type": "object",
    "properties": {
      "proxy": { "anyOf": [{ "type": "string", "enum": ["rtk", "headroom"] }, { "type": "array", "items": { "type": "string", "enum": ["rtk", "headroom"] }, "minItems": 1 }] },
      "repo": { "type": "string" },
      "tasks": { "type": "string" },
      "live": { "type": "boolean" },
      "confirmCost": { "type": "boolean" },
      "liveMaxTasks": { "type": "integer", "exclusiveMinimum": 0 }
    },
    "required": ["proxy"]
  }
}

このリポジトリで実際に tools/call を実行すると、{"name": "verify_proxy_savings", "arguments": {"proxy": "rtk"}}、CLI の --format json 出力と同じ形式が返されます（ここでは省略しています。稼働中の呼び出しでは TT01/TT02/TT05 のエントリを含む records 配列全体が返されます）。

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"run_id\": \"tt_2026-07-18_f88644\",\n  \"repo\": \"...\",\n  \"task_corpus_size\": 23,\n  \"proxies\": [\"rtk\"],\n  \"records\": [ /* TT01, TT02, TT05 -- same shape as `verify --format json` */ ],\n  \"tt03\": { \"rtk\": { \"pass\": false, \"regressed_count\": 2, \"task_corpus_size\": 23 } },\n  \"tt05\": { \"rtk\": { \"pass\": true, \"message\": \"No regression vs. last-verified rtk 0.43.0 baseline (stored 2026-07-18).\", \"prior_run_id\": \"tt_2026-07-18_608b74\", \"degraded\": false } }\n}"
    }
  ],
  "isError": false
}

基盤となる runVerify() 呼び出しが CLI でゼロ以外の終了コードを返す場合、レポートは返されず、isError は true になります。該当するケースは、プロキシのバイナリが見つからない場合、タスクコーパスが無効な場合、または --live の安全ゲートが確認不足の呼び出しを拒否した場合です。MCP モードでは、通常 tokentrust verify が stdout に出力する進捗情報とトレースログは stderr に振り分けられます。stdio トランスポートが接続されると、stdout は稼働中の JSON-RPC 通信に使用されるためです。

プロキシのサポート

プロキシ	状態
rtk	完全にサポートされています。実際のサブプロセスによる検証を行います（stdin 形式のタスクには rtk pipe --filter <name>、ファイルベースのタスクには rtk read -l aggressive <files> を使用します）。
headroom	認識されます（--proxy headroom は有効なフラグ値です）が、まだサポートされていません。headroom は HTTP プロキシサーバーであり、単発の圧縮 CLI ではないため、現在のサブプロセスベースのハーネスでは実行できません。tokentrust verify --proxy headroom はメッセージを出力してスキップするため、何も知らせずに失敗することはありません。

比較

	内容	継続的／セルフサービス	特定の主張を検証
TokenTrust	ラベル付きタスクコーパスに対して名前付きプロキシを実行し、実際の圧縮率、コスト、出力品質の低下を測定して、主張値と測定値を表示します	はい。独自のリポジトリで、独自の CI 上で、プロキシのバージョンが更新されるたびに実行できます	はい。それがまさに目的です
tokbench	実際のエージェント型 SDLC タスクで rtk、headroom、lean-ctx を評価する独立したパイロットベンチマーク。生のトランスクリプトと事前登録済みのプロトコルを公開しています	いいえ。単一リポジトリでのパイロットレポートで、再現実験を進行中です	はい、厳密に検証します。正当な功績は正当に評価します
Langfuse、Vantage、Finout、Amnic、Revenium	LLM／AI のコスト可観測性と FinOps。モデルやプロバイダー全体にわたって実際の API 支出を追跡し、チームごとに割り当てます	はい。ホスト型またはセルフホスト可能で、継続的に利用できます	いいえ。これらは支出額を追跡しますが、特定のプロキシが主張する特定の節約効果が妥当かどうかは確認しません

tokbenchは最も近い先行事例であり、正当に評価されるべきです。厳密で、情報も公開されていますが、パイロットの範囲は最初に読んだ印象よりも限定的です。1つのリポジトリ、1つのタスク、各群 N=1 で、再現実験を進行中です。そのパイロットで得られた数値は、ぜひ直接ご覧ください。2.28M トークンのネイティブベースラインに対するプロバイダー請求の入力トークン数は、rtk で 2.89M（+27%）、headroom で 3.24M（+43%）でした。headroom は実際にワイヤー上のトークンを 342K 圧縮していたにもかかわらずです。1ターンあたりのペイロードが減る一方で、エージェントのターン数が増えたためです。これは実際に有用な、独立して得られたデータポイントであり、「圧縮された」と「安くなった」の間にある隔たりを、公開された単一のパイロットではなく、独自のリポジトリで継続的に検出し続けることこそ、TokenTrust が存在する理由です。

これが必要な理由

コンテキスト削減プロキシ（rtk、headroom など）は、自身の README で圧縮率やコスト削減の数値を公開しています。その数値は、メンテナー自身のベンチマークを、メンテナー自身のワークロードで実行した結果であり、プロジェクト外の誰も計算を確認していません。これは非難ではありません。この分野のあらゆるプロキシが現在、自らの数値を報告する方法にすぎず、メンテナーが自分のツールをベンチマークしても、敵対的なテストにはなりません。

この隔たりは、プロキシ自身の課題トラッカーにも表れています。

• rtk#839は、rtk の実際の節約効果が主張とどれほど一致するかを問う、5つのリポジトリと2,100件の測定を対象にした、公開中の実証ベンチマークのスレッドです。
• rtk#1935、「rtk gain がトークン使用量と節約額を大幅に幻覚する」（公開中）。
• rtk#582、「RTK Hook により Claude Code のコストが18%増加」。メンテナー自身のテストスイートでは検出できなかったコストの回帰です。TT05 は、ユーザーが気づく前に、この種の回帰を検出するために特化して存在します。

TokenTrust は、これらのプロキシと競合するものではありません。プロキシを検証します。プロキシの主張する数値が妥当かどうかで利害が左右されることはなく、各カテゴリの実行結果には、主張値と測定値が必ず並べて表示されるため、比較結果が隠されたり、平均化されて見えなくなったりすることはありません。

また、独自の測定に含まれていたバグも発見し、修正しました。あるフィクスチャのベースラインが、本来の生の git log ではなく、誤って git log --oneline で取得されていたため、そのタスクでの rtk の実際の圧縮率が約42ポイント低く見積もられていました。正しい方法で再取得した結果、verify-git-log-filter の測定値は95.4%となり、コーパス内で最も高い削減率となりました。これは実際の数値です。コミット e42246cに修正内容があります。フィクスチャを実行せずに測定値を公開することはありません。この同じコミットでコーパスを15タスクから現在の23タスクに拡張したため、FAQ に記載されているように、古い件数に触れたヘルプ文字列が1つ残っているものの、上記の実際の実行出力には「23 labeled tasks」と表示されます。

TokenTrust とは何か、なぜ存在するのか

TokenTrust は、AI コーディングエージェントのコンテキスト削減プロキシがうたうトークンとコストの削減効果が、スプレッドシートによる推定ではなく、ローカルトークナイザーを使って実際のラベル付きタスクコーパスを実行した場合にも成り立つかを測定するコマンドラインツールです。圧縮プロキシは現在、自らの削減数値を自己申告しており、導入前にそれを検証する独立した、再現可能な CI ネイティブの方法がないことから、TokenTrust は生まれました。TokenTrust 自体はプロキシではなく、何も圧縮しません。圧縮プロキシを検証するツールです。

実環境での検証

TokenTrust 自身の検証作業は、すでに実際の、独立して追跡されている GitHub の issue に反映されています。rtk-ai/rtk#1313（@ChrisEdwards が起票し、損失のないモードと、エージェントのコンテキストで切り捨てが引き起こすサイレント障害についての正直な説明を rtk に求めたもの）は、当初、rtk の既存の仕組みでは部分的にしか対応できていないと検証されました。TokenTrust 自身のフィクスチャに、どちらであるかを証明するのに必要な品質マーカーがまだ含まれていなかったためです。TokenTrust の pipe --filter フィクスチャのうち 3 つに、実際に検証済みの品質マーカーを追加したことで、rtk ではなく TokenTrust 自身の計測におけるその不足が解消されました。これにより、主張ではなく実際の rtk 0.43.0 バイナリを使って、rtk の既存の never-worse ガード機構がすでに issue の要望どおりに機能していることを確認できました。その結果、issue の判定は部分的な対応から、再検証済みの明確な合格へと変わりました。TokenTrust は rtk のリポジトリには一切手を加えていません。すでに正しかったことを証明できるだけの精度を備えたのです。

Python パッケージ

pip install tokentrust-cli でインストールされるのは、Node バイナリをラップしたものではなく、本格的な Python 移植版と同じ tokentrust CLI です。python/src/tokentrust/ に実際の Python ソースがあり、独自の pytest テストスイートと、ホイールにそのままコピーされた同一の 23 タスクコーパスが含まれています。どちらの配布版も同じ cl100k_base トークナイザーのエンコーディングを使用し、実際のサンプルテキストでトークン数が一致することを検証済みです。今後も両方を一体としてメンテナンスします。これには tokentrust mcp も含まれます。Python 移植版は、npm パッケージと同じ verify_proxy_savings MCP ツールを、バイト単位で同一のワイヤースキーマで公開します（python/README.md の「Agent-native / MCP」セクションを参照）。インストール方法は python/README.md、手順ガイドは python/docs/getting-started.md、両方のパッケージで共有される検証手法は python/docs/concepts.md を参照してください。

FAQ

TokenTrust とは何ですか。また、rtk や headroom のようなコンテキスト削減プロキシとはどう違いますか？ TokenTrust 自体はプロキシではなく、何も圧縮しません。ベンダーに依存しない検証レイヤーです。rtk や headroom のようなプロキシを実際のサブプロセスとして、固定されたラベル付き 23 タスクコーパスに対して実行し、ローカルトークナイザーで実際のトークンとドルの削減量を測定して、その測定値をプロキシ自身の README に記載された数値と並べて表示します。差別化要因は独立性です。TokenTrust は、プロキシがうたう数値が成り立つかどうかについて利害関係がないため、差を平均して見えなくすることはありません。

TokenTrust はどのプラットフォームで動作しますか。また、npm と PyPI のパッケージは同じツールですか？ どちらも同じツールの本格的な個別の移植版であり、一方がもう一方をラップしているわけではありません。npm install -g tokentrust-cli（または npx tokentrust-cli）で Node.js ビルドをインストールできます。pip install tokentrust-cli で、独自の pytest テストスイートを備えた実際の Python 移植版を python/src/tokentrust/ にインストールできます。どちらも同じ tokentrust コマンド、同じ TT01-TT05 カテゴリー、同じ同梱タスクコーパス、同じ cl100k_base トークナイザーのエンコーディングを公開します。 TokenTrust はシェルからだけでなく、AI エージェントから直接利用できますか？ はい。tokentrust mcp（または npx tokentrust-cli mcp）を実行すると、標準入出力を介して MCP（Model Context Protocol）サーバーが起動し、verify_proxy_savings という 1 つのツールが公開されます。このツールは、CLI が使用するものと同じ runVerify() エンジンを利用します。Claude Code や Claude Desktop を含む、MCP 互換のクライアントでこのツールを呼び出すと、コマンドラインで --format json を指定したときと同じ構造化 JSON レポートが返されます。

ほかの独立したプロキシベンチマークである tokbench と TokenTrust はどう違いますか？ tokbench は先行する重要な取り組みであり、評価に値します。生のトランスクリプトを公開し、プロトコルを事前登録した、厳密なパイロットです。現在の対象範囲は、最初に読んだときの印象よりも狭く、1 つのリポジトリ、1 つのタスク、各群 N=1 で、現在は再現実験が進行中です。一方、TokenTrust は 23 タスクのコーパスを継続的に実行します。公開済みのパイロットレポートを 1 回作成するのではなく、プロキシのバージョンが更新されるたびに、独自の CI で独自のリポジトリを対象に実行できます。

npm パッケージの tokentrust verify --help には、デフォルトのタスクコーパスは 15 タスクと書かれています。正しいのは 15 ですか、それとも 23 ですか？ 正しいのは 23 です。バンドルされたコーパスはコミット e42246cで 15 タスクから 23 タスクに拡張され、実際の実行では（npm と PyPI の両方で）、出力の先頭に「Task corpus: 23 labeled tasks」と表示されます。これは実際の fixtures/tasks.yml ファイルの内容と一致します。npm パッケージの --tasks フラグのヘルプテキストには、この拡張前の文字列が残っており、23 タスクという記載に更新されていません。PyPI パッケージのヘルプテキストには、すでに正しく 23 と記載されています。影響するのは --help テキストの表示のみで、CLI が実際に実行するタスクには影響しません。

使用している Python のバージョンで pip install tokentrust-cli が失敗した場合はどうすればよいですか？ PyPI パッケージの pyproject.toml には requires-python = ">=3.10" と宣言されているため、Python 3.9 以前では pip によるインストールが拒否されます。Python 3.10、3.11、3.12、または 3.13（パッケージのテスト対象バージョン）にアップグレードするか、代わりに npm パッケージを使用してください。npm パッケージに必要なのは Node.js 18 以降のみです。

TokenTrust を商用利用できますか？クレジット表記は必要ですか？ はい。TokenTrust は Apache-2.0 ライセンス（LICENSEを参照）で提供されており、クローズドソース製品内での利用を含め、商用利用、変更、再配布が許可されています。ただし、ライセンスと著作権表示を保持し、ソース自体に加えた変更を明記する必要があります。

TokenTrust はコードやプロキシの圧縮出力を変更しますか？ いいえ。フィクスチャタスクに対してプロキシを実際のサブプロセスとして実行し、出力を取得して測定します。リポジトリ内の内容やプロキシの設定は変更されません。

TokenTrust は、推定値ではなく、プロキシの実際のプロバイダー請求額を検証できますか？ はい。--live --confirm-cost を指定すると、デフォルトでは --live-max-tasks により最大 5 タスクに制限して実行できます。ご自身の API キーを使用し、推定費用を先に表示することなく実際の課金が発生することはありません。

TokenTrust はライブラリとしてインポートできますか？それとも CLI 専用ですか？ 現時点では CLI 専用です。npm パッケージも PyPI パッケージも、ドキュメント化されたインポート可能な公開 API を提供していません。npm の package.json には、公開パッケージに実際には含まれていないファイルを指す main エントリが記載されており、PyPI パッケージのトップレベルモジュールがエクスポートするのはバージョン文字列のみです。tokentrust コマンドまたは verify_proxy_savings MCP ツールを使用してください。このパッケージの検証ロジックを直接 import／require する、サポート対象の方法はまだありません。

コントリビューション

プロジェクトの構成、検証カテゴリやフィクスチャタスクの追加方法、カテゴリの変更ごとに満たす必要があるカバレッジ基準については、npm パッケージと PyPI パッケージの両方を対象に、CONTRIBUTING.mdを参照してください。

ライセンス

Apache-2.0。LICENSEを参照してください。