contextbudget

contextbudget

contextbudget は、エージェントのコンテキストウィンドウに対するディレクトリツリーのトークンコストを推定します。ツリーを走査して各テキストファイルのコストを推定し、合計を予算と比較したうえで、最も大きなファイルとスキップされたサブツリーを報告します。これにより、ツリー全体がウィンドウを使い切る前に、除外するものを判断できます。

推定について、正直に説明します

このツールのトークン数はヒューリスティックによる推定値であり、トークナイザーで数えた値ではありません。contextbudget は、対象となる各ファイルを UTF-8 テキストとしてデコードし、決定的なルールを 1 つ適用します。トークン数 = ceil（文字数 / 4）。ここで文字数とは、デコードされたテキストの長さです。実際のトークナイザーはモデルによってテキストの分割方法が異なるため、同じファイルでも実際のトークナイザーで数えると異なる数になり、ときには多く、ときには少なくなります。この数値は、ファイル同士を比較したり、特に大きなファイルを順位付けしたり、ツリーを大まかな予算と照合したりするために使用してください。特定のモデルが請求または受け入れる量を正確に予測する値として使用しないでください。

インストール

npx @reneturcios/contextbudget budget [path]

また、自作ツールの依存関係としてインストールし、以下の MCP サーバー形式で使用することもできます。このパッケージには Node 20 以降が必要です。

CLI の使用方法

contextbudget budget [path] [--json]
contextbudget mcp
contextbudget --version

• budget [path]：path にあるツリーを確認します。path のデフォルトはカレントディレクトリです。人が読みやすいレポート、または --json を指定した場合は完全な JSON レポートを出力します。
• mcp：stdio 経由で MCP サーバーを実行します。
• --version：バージョンを出力します。

終了コード：

• 0：判定結果は WITHIN-BUDGET です。
• 1：その他の判定結果です。現在は OVER-BUDGET のみです。
• 2：使用方法に誤りがあるか、対象が存在しません。
• 141：読み取り側が出力パイプを早期に閉じました（シェル上で SIGPIPE が発生した場合に相当します）。

予算

デフォルトの予算は推定トークン数 200000 です。環境変数 CONTEXTBUDGET_BUDGET に正の整数を設定すると、別の予算を使用できます。

CONTEXTBUDGET_BUDGET=50000 contextbudget budget ./src

この変数が未設定、解析不能、または正の値でない場合は、デフォルトの 200000 が適用されます。

判定ルール

• 推定トークン数の合計が予算以下の場合、判定結果は WITHIN-BUDGET となり、それ以外の場合は OVER-BUDGET となります。
• デフォルトでは、以下のディレクトリはスキップされ、内部には入りません：node_modules、.git、dist、coverage、.next、vendor。
• 1 MiB（1048576 バイト）を超えるファイルはスキップされ、カウントされません。
• 最初の 4 KiB に NUL バイトがあることで検出されたバイナリファイルは、スキップされ、カウントされません。
• シンボリックリンクはたどりません。

検出内容：

• カウント対象ファイルの推定トークン数が予算の 10 パーセントを超えるたびに、重大度 high の検出結果が 1 件記録されます。ルールは large-file です。
• 1 MiB の上限を超えたためにスキップされたファイルごとに、重大度 medium の検出結果が 1 件記録されます。ルールは skipped-large です。
• デフォルトのスキップリストによってスキップされたディレクトリごとに、重大度 info の検出結果が 1 件記録されます。ルールは skipped-dir です。

順序は決定的です。ファイルは推定トークン数の降順、次にパスの昇順で順位付けされ、ディレクトリエントリーは名前の昇順で走査されます。レポートにタイムスタンプは含まれません。

レポートの形式

JSON レポートには、tool、version、target、verdict、counts、findings、summary が含まれます。主な数値は counts にあります。

• files：カウントされたファイル数。
• totalTokens：カウントされたファイル全体の推定トークン数。
• totalChars：カウントされたファイル全体の文字数。
• budgetTokens：適用される予算。
• remainingTokens：予算から合計を差し引いた値。予算超過の場合は負の値になります。
• skippedDirs、skippedBinary、skippedLarge：スキップされた対象の数。
• findings、findingsHigh、findingsMedium、findingsInfo、findingsLow：検出結果の数。
• ext:<extension>:files と ext:<extension>:tokens：拡張子ごとの合計。たとえば ext:.ts:tokens です。
• top:<relative path>：最も大きなファイル上位 10 件それぞれの推定トークン数。

MCP

MCP サーバーは、以下のツールを 1 つ公開します。

• budget_path：path 文字列を受け取り、contextbudget budget <path> --json と同じ JSON レポートを返します。

contextbudget mcp を実行するか、server.json のレジストリエントリーから実行してください。

制限事項

• テキストファイルのみが対象です。バイナリファイルとサイズが1 MiBを超えるファイルはスキップされるため、実際のコストはスキップ数と、大きなファイルについては中程度の検出結果としてのみレポートに反映されます。
• 上記のとおり、推定はヒューリスティックです。トークナイザーではなく、特定のモデルの語彙も把握していません。
• スキップリストは固定です。このバージョンでは、ディレクトリごとのカスタムスキップやカスタム予算を設定するフラグや設定ファイルはありません。予算を制御する方法はCONTEXTBUDGET_BUDGETのみです。
• カウントの対象はファイルの内容のみです。ファイル名、ディレクトリ名、エージェントハーネスがファイルの内容に追加する前後の枠組みは推定されません。

開発

npm install
npm run build
npm test