Agent Booster

このリポジトリはアーカイブされています。 Agent Booster は現在、sseshachala/conductai → tools/booster にあります。PyPI からインストールしてください（pip install agent-booster）。イシューや PR は conductai で報告してください。

Agent Booster

重要なコードだけをルーティングして、AI コーディングエージェントのトークンコストを 5～15 倍削減します。

読み取りのたびにソースファイル全体をモデルに送る代わりに、Agent Booster はコードベースのシンボルインデックスを作成し、現在のタスクに関連する関数とクラスだけを返します。

---

仕組み

Without Booster                    With Booster
─────────────────                  ────────────────────────────
Read executor.py                   smart_read executor.py + task
→ 1,881 lines (~6k tokens)         → 3 matching functions (~200 tokens)

5 つのレイヤーが連携します。

レイヤー	機能
シンボルインデックス	tree-sitter がすべての .py、.ts、.tsx、.js、.jsx ファイルを解析し、関数とクラスを抽出して SQLite に保存します
ベクトル埋め込み	sentence-transformers が各シンボルをエンコードし、セマンティック検索を可能にします
スマート読み取り	ファイルとタスクを指定すると、ファイルごとにベクトル検索を実行し、一致するシンボルの行範囲だけを返します
MCP サーバー	stdio 経由で 4 つのツールを公開します。MCP 対応のエージェントならどれでも呼び出せます
プラットフォーム初期化	1 つのコマンドで、Claude Code、Cursor、Windsurf、または Codex 用の適切な設定を書き込みます

---

インストール

Python 3.10 以降が必要です。

pip install agent-booster          # symbol index + MCP tools
pip install agent-booster[embed]   # + semantic vector search (recommended)

---

クイックスタート

ステップ 1 — AI ツールを接続する

booster init claude     # Claude Code
booster init cursor     # Cursor
booster init windsurf   # Windsurf
booster init codex      # OpenAI Codex CLI
booster init all        # all four

各コマンドは、変更されるファイルを正確に表示し、確認を求めてから書き込みます。すべて元に戻せます。

booster remove claude   # or cursor, windsurf, codex, all

例 — OpenAI Codex を接続する（booster init codex → booster start → booster gain）：

セッションごとではなく、プロジェクトごとに 1 回実行してください。 フックはプロジェクトのルートにある .claude/settings.json と .mcp.json に保存されます。 このディレクトリで起動したすべての Claude Code セッションで、どのターミナルウィンドウからでも、同じマシンであれば自動的に読み込まれます。 セッションごとの設定は不要です。

ステップ 2 — コードベースにインデックスを作成する

プロジェクトのルートから 1 回実行してください。大規模なリファクタリングの後は再実行してください。

booster index && booster embed
# Indexed 260 files, 1800 symbols.
# Built embeddings for 1800 symbols.

インデックスは .booster/（Git の追跡対象外）に保存されます。インデックスはすべてのセッションで共有されます。

ステップ 3 — AI ツールを再起動する

これで、すべてのセッションで agent-booster MCP サーバーを利用できます。Claude Code（およびその他のツール）は、インデックス済みのファイルに対して smart_read と search_context を自動的に使用します。

ステップ 4 — 節約量を追跡する

booster gain

---

CLI リファレンス

booster init <platform>

対象プラットフォーム用の MCP サーバー設定とルールファイルを書き込みます。変更を加える前に確認を求めます。

booster init claude     # .mcp.json + CLAUDE.md + .claude/settings.json hook
booster init cursor     # .cursor/mcp.json + .cursorrules
booster init windsurf   # ~/.windsurf/mcp.json + .windsurfrules
booster init codex      # ~/.codex/config.json + AGENTS.md
booster init all        # all four

booster init claude --yes   # skip confirmation (CI/scripts)

booster remove <platform>

init で書き込んだ内容をすべてきれいに元に戻します。残留物はありません。

booster remove claude
booster remove cursor
booster remove windsurf
booster remove codex
booster remove all

booster index

現在のディレクトリからすべての .py、.ts、.tsx、.js、.jsx ファイルをスキャンします。関数、クラス、メソッド、インターフェースを抽出して .booster/symbols.db に保存します。node_modules、.venv、__pycache__、.git、.booster、.next、dist、build はスキップします。

booster index
# Indexed 260 files, 1800 symbols.

booster embed

インデックス済みのすべてのシンボルについて、sentence-transformer のベクトル埋め込みを作成します。セマンティックな search_context 呼び出しに必要です。all-MiniLM-L6-v2 を使用します（ローカルで動作し、データがマシンの外部に送信されることはありません）。

booster embed
# Built embeddings for 1800 symbols.

booster search "<query>"

インデックス済みのすべてのシンボルを対象に、キーワード検索を行います。ファイルパス、行番号、種類、名前、シグネチャを返します。

booster search "guard install"
# apps/web/src/app/settings/modules/page.tsx:99  function handleInstall  function handleInstall() {

booster route "<task>"

タスクの複雑さに基づいて、haiku、sonnet、opus のいずれかを推奨します。判断にはキーワードの手がかり、ファイル数、シンボル数を使用します。

booster route "fix the guard SSE role check"
# haiku  (narrow task — 0 symbol(s) in 1 file)

booster route "refactor the entire runtime compiler and DSL layer"
# opus  (matches complexity keywords)

booster serve

stdio 経由で MCP サーバーを起動します。booster init で設定すると、Claude Code、Cursor、Windsurf、Codex によって自動的に呼び出されます。通常、直接実行する必要はありません。

booster gain

過去の smart_read 呼び出しによるトークン節約量を表示します。読み取りの合計数、提供したトークン数と節約したトークン数、節約率、節約量の多いファイルを確認できます。

Agent Booster — Token Savings Report
─────────────────────────────────────
Active days:        3
Total reads:        47
Tokens served:      12,400
Tokens saved:       89,200
Savings rate:       88%

Top files by savings:
  executor.py              18,400 tokens saved  (12 reads)
  guard.py                 14,200 tokens saved  (8 reads)

---

MCP ツール

booster serve が実行されると、以下の 4 つのツールをエージェントが利用できます。

get_symbols(file)

ファイル内でインデックス化されたすべてのシンボルを返します。名前、種類、行の範囲、シグネチャが含まれます。ファイルを読み込む必要はありません。

Input:  { "file": "apps/api/app/runtime/executor.py" }
Output: function run_workflow (lines 42-89): def run_workflow(...)
        class WorkflowState (lines 91-140): class WorkflowState:

search_context(task)

インデックス内のすべてのシンボルを対象に、意味ベースのベクトル検索を行います。コサイン類似度が高い上位 10 件を返します。埋め込みが作成されていない場合は、キーワード検索に切り替わります。

Input:  { "task": "guard install uninstall" }
Output: apps/web/src/app/settings/modules/page.tsx:99 function handleInstall — function handleInstall() {
        apps/web/src/components/guard/GuardNav.tsx:13 function GuardNav — function GuardNav() {
        ...

smart_read(file, task)

ファイル単位のベクトル検索を行い、一致したシンボルのソース行のみを返します。名前と行の範囲を示すヘッダーも含まれます。一致するシンボルがない場合は、モデルがファイル全体を黙って受け取るのではなく、通常の Read に切り替えるよう明示的なメッセージを返します。

Input:  { "file": "apps/api/app/runtime/executor.py", "task": "execute output block" }
Output: # function _execute_output (lines 1165-1210)
        def _execute_output(block, state, credentials, ...):
            ...

route_model(task, files?)

タスクの複雑さを示す情報に基づき、haiku、sonnet、opus を推奨します。files が省略された場合は、search_context を使って自動検出します。

Input:  { "task": "fix the login redirect bug" }
Output: { "model": "haiku", "reason": "narrow task — 1 symbol in 1 file" }

---

booster init claude が書き込む内容

ファイル	変更内容
.mcp.json	mcpServers に agent-booster を追加します
CLAUDE.md	Booster の使用ルールを含むブロック（センチネルマーカー）を追記します
.claude/settings.json	PreToolUse（Read + Grep）と UserPromptSubmit のフックを設定します
.claude/hooks/booster-gate.py	インデックス化されたファイルに対する Read をブロックし、smart_read を強制します
.claude/hooks/booster-grep-nudge.py	意味ベースの Grep パターンを search_context に誘導します
.claude/hooks/booster-route.py	route_model を自動実行し、ユーザーが発言するたびに haiku／sonnet／opus を推奨します

booster remove claude を実行すると、6 つすべてが残さず削除されます。

---

どのように機能するか

Agent Booster は、3 層構成のトークン削減スタックの第 3 層です。

Layer 3 — Agent Booster     AST+semantic routing, smart file reads
Layer 2 — RTK               Token compression on CLI/git/build output
Layer 1 — Prompt caching    Stable context reuse (native to Claude Code + API)

各層は独立しており、個別に追加できます。

---

よくある質問

2 つ目のターミナルを開いた場合も動作しますか？ はい。フックは特定のターミナルセッション内ではなく、プロジェクトルートの .claude/settings.json と .mcp.json に設定されます。このプロジェクトで新しい Claude Code ウィンドウを開くと、フックが自動的に読み込まれます。

マシンを再起動した後、booster init をもう一度実行する必要がありますか？ いいえ。booster init はファイルを一度ディスクに書き込みます。ファイルは再起動後もセッションをまたいで保持されます。再実行が必要なのは、それらのファイルを削除した場合、または新しいプロジェクトに切り替えた場合のみです。

チームメイトも booster init を実行する必要がありますか？ はい。開発者ごと、プロジェクトごとに 1 回実行する必要があります。.mcp.json と .claude/settings.json をリポジトリにコミットすると、チームメイトがクローンしたときにフックも利用できるようになります。ただし、シンボルインデックスは gitignore の対象のため、各自の環境で pip install agent-booster[embed] と booster index && booster embed を実行する必要があります。

完全に元に戻せますか？ はい。booster remove claude を実行すると、6 つすべてのファイルを削除し、設定項目もクリーンアップします。何も残りません。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "agent-booster": {
      "command": "booster",
      "args": ["serve"]
    }
  }
}

Claude Desktop を起動する前に、プロジェクトルートで booster index && booster embed を 1 回実行してください。環境変数は不要です。

---

プロジェクト構成

tools/booster/
├── README.md
├── pyproject.toml
└── booster/
    ├── cli.py          # click commands: index, embed, search, serve, init, remove, route, gain
    ├── indexer.py      # tree-sitter parser + SQLite symbol store + vector search
    ├── retriever.py    # smart_read: per-file vector search → relevant line slice
    ├── mcp_server.py   # MCP server: get_symbols, search_context, smart_read, route_model
    └── stats.py        # token savings tracking (booster gain)