model-shunt

Model-Shunt 🔀

Spotify Engineering が最初に考案した、Shunt モデルルーティングパターンを疎結合かつ依存関係なしで実現する、汎用的な実装です。

Model-Shunt を使うと、AI コーディングエージェント（Antigravity、Cursor、Windsurf、Claude Code、Aider、OpenHands など）は、トークンを大量に消費する I/O（ファイルの一括読み取り／コード分析）や、繰り返し発生する定型コードの生成（テスト、モック、スタブ、設定）を、高速、低コスト、またはローカルのワーカーモデル（Gemini 2.5 Flash、Groq/Llama、Ollama、DeepSeek、GPT-4o-mini）に委任できます。これにより、メインのコンテキストウィンドウをすっきり保ちながら、メインエージェントのトークン消費を最大 90% 削減できます。

---

⚡ 主な特長

• 外部依存関係なし： 純粋な Python 3 標準ライブラリ（urllib、json、re、argparse）で構築されています。pip install、仮想環境、npm は不要です。
• エージェントに依存しません： 標準の MCP（Model Context Protocol）、単体の CLI スクリプト、または PreToolUse ライフサイクルフックを通じて、あらゆる AI コーディングエージェントでシームレスに動作します。
• 動的なモデル検出と自動ルーティング： ワーカーのエンドポイントにリアルタイムで問い合わせて利用可能なモデルを検出し、タスクに最適なモデルへ自動的にルーティングします。
  • 読み取りモード（一括 I/O）： 大規模なコンテキストウィンドウと非常に低いコストを優先します（例：gemini-2.5-flash、llama-3.3-70b-versatile、gpt-4o-mini）。
  • 書き込みモード（コード生成）： コーディングに特化したモデルを優先します（例：qwen2.5-coder:latest、gemini-2.5-flash、deepseek-chat）。
• Linux の ARG_MAX 制限を回避： ファイルの内容を CLI 引数として渡す単純な実装（Linux では約 128 KB に制限されます）とは異なり、Model-Shunt はコーパスデータを stdin 経由でストリーミングするため、バッファーオーバーフローを起こさずに数十万行を分析できます。
• 決定的な行番号付け（N|）： ファイルブロック内の各行に 1 から始まるインデックスを自動的に付け、検証可能で正確な行番号を引用するようワーカーモデルに促します。位置を幻覚することはありません。
• バイナリファイルの保護： LLM に送信する前にバイトヘッダーを調べ、バイナリファイル（PDF、画像、コンパイル済みオブジェクト）を拒否します。
• ネットワークの耐障害性： レート制限（HTTP 429）や一時的なサーバーエラー（HTTP 503/502）に対して、自動的に指数バックオフで再試行します。タイムアウトとトークン制限も設定できます。
• 大規模コーパス向け Map-Reduce： bulk_read のペイロードが直接処理の上限（SHUNT_MAX_DIRECT_TOKENS、デフォルトで約 200k トークン）を超えると、Model-Shunt はコーパスを自動的にチャンクに分割し、各チャンクに質問を適用して（絶対行番号 N| を保持）、抽出結果をまとめて出典付きの回答を作成します。1 行が非常に長いファイル（圧縮済み JSON/JS）は、明示的な位置マーカーを付けて文字単位で分割されます。レート制限時は失敗するのではなく、プロバイダーのクォータ制限が解除されるまで待機します。

---

📁 リポジトリ構成

model-shunt/
├── src/model_shunt/
│   ├── worker.py              # Universal LLM worker engine with model discovery (zero-deps)
│   └── server.py              # Stdio MCP server exposing routing tools
├── bin/model-shunt.js         # npm/npx launcher shim (requires local Python 3)
├── plugin/
│   ├── .claude-plugin/        # Plugin manifest for hook-compatible agents
│   ├── hooks/                 # PreToolUse interceptor hooks (check-file-size, check-bash-read)
│   ├── scripts/               # Executable streaming CLIs (bulk-read, code-write)
│   └── skills/                # Agent skill manifests (/bulk-reader, /code-writer)
├── pyproject.toml             # PyPI packaging (uvx / pip install)
├── package.json               # npm packaging (npx)
├── config.example.json        # Configuration template
├── test_shunt.py              # Automated test suite
└── .gitignore                 # Credential and cache protection

---

⚙️ 設定

環境変数または config.json ファイル（~/.config/model-shunt/config.json またはプロジェクトのルートに配置）を使って、ワーカーモデルを設定します。

config.jsonを使用する

{
  "provider": "gemini",
  "model": "auto",
  "timeout": 90,
  "max_tokens": 8192
}

ヒント： "model": "auto"を設定するか、CLIで--auto-modelを渡すと、プロバイダーで有効なモデルが自動的に確認され、読み取りと書き込みに最適なモデルが選択されます。

セキュリティ： APIキーをconfig.jsonに記述しないでください。代わりに環境変数を使用してください（例：GEMINI_API_KEY、GROQ_API_KEY、SHUNT_API_KEY）。最終手段としてapi_keyフィールドも用意されていますが、秘密情報をファイルに保存しないことを強く推奨します。

環境変数を使用する

# Google Gemini (Recommended: 1M token context, high speed, ultra-low cost)
export SHUNT_PROVIDER="gemini"
export GEMINI_API_KEY="your-api-key"

# Groq (Ultra-low latency inference)
export SHUNT_PROVIDER="groq"
export GROQ_API_KEY="your-api-key"

# Ollama (100% private, local, and free)
export SHUNT_PROVIDER="ollama"
export SHUNT_BASE_URL="http://localhost:11434/v1"

# OpenAI / DeepSeek / OpenRouter / Anthropic
export SHUNT_PROVIDER="deepseek"
export DEEPSEEK_API_KEY="your-api-key"

---

🛠️ 使用モード

モード1：汎用MCPサーバー（推奨）

Model-Shuntは、次の3つのツールを公開する標準的なstdio MCPサーバーを提供します。

1. get_available_models(provider?)：プロバイダーのエンドポイントに問い合わせ、読み取り用と書き込み用のモデルを推奨します。モデルの検出に失敗した場合、または検出がサポートされていない場合は、現在の利用可否が確認されていない組み込みの推奨モデルを返します。
2. bulk_read(question, file_paths, model?, provider?)：大容量のファイルや複数のファイルを読み取り、正確な行番号の引用を含む、簡潔で構造化された箇条書きを出力します。引用name (N|k)は、ソースのk行目にその名前が含まれていない場合は除外されます。
3. code_write(spec, reference_path, target_path?, model?, provider?)：仕様と参照ファイルを使用してコードを生成します。target_pathを省略するとコードを返し、指定すると、存在しない親ディレクトリを作成したうえでコードを書き込み、既存の対象ファイルがあれば上書きします。

bulk_readは、選択したファイルと質問を設定済みのワーカープロバイダーに送信し、code_writeは、仕様と参照ファイルを送信します。プロバイダーには、リモートまたはローカル（Ollamaなど）を使用できます。トークンの節約効果は、入力と応答によって異なります。

MCPサーバーはローカルでstdio経由で実行されます。プロバイダーの認証情報は環境変数で設定してください。ファイルアクセスでは解決済みパスが使用されるため、許可されたワークスペースのルート外を指すシンボリックリンクは拒否されます。無効なリクエストは構造化されたエラーを返し、その後の呼び出しでもサーバーを利用できます。

インストール

MCP Registry名：mcp-name: io.github.yasmanycastillo/model-shunt

汎用ワンライナー（uv／pip／pipx／npmを検出してmodel-shuntコマンドをインストールし、Claude Codeが存在する場合は登録します）：

curl -fsSL https://yasmanycastillo.github.io/model-shunt/install.sh | bash

手動での代替方法：

claude mcp add model-shunt -- uvx model-shunt      # if you have uv
claude mcp add model-shunt -- npx -y model-shunt   # if you have Node + Python

任意のMCPクライアント（Cursor、Windsurf、Antigravity、Claude Desktopなど）— MCP設定に追加します。クローンや絶対パスは不要です。

{
  "mcpServers": {
    "model-shunt": {
      "command": "uvx",
      "args": ["model-shunt"],
      "env": {
        "SHUNT_PROVIDER": "gemini",
        "SHUNT_MODEL": "auto",
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

フォールバック（オフライン／uvなし／npxなし）： Python 3.9以降を使用して、クローンから直接実行できます。"command"／"args"を"command": "python3", "args": ["/absolute/path/to/model-shunt/src/model_shunt/server.py"]に置き換えてください。

セキュリティ： デフォルトでは、bulk_read／code_writeはサーバーの作業ディレクトリ（エージェントのワークスペース）内のファイルのみを操作します。SHUNT_ALLOWED_ROOTS（PATH形式のリスト）を設定すると、サンドボックスの範囲を拡大できます。

Map-Reduceの調整（任意）

変数	デフォルト	目的
SHUNT_MAX_DIRECT_TOKENS	200000	推定サイズがこの値を超えるペイロードはMap-Reduceに切り替わります
SHUNT_CHUNK_CHARS	600000	チャンクの文字数（約150kトークン）
SHUNT_CHUNK_RETRIES	3	レート制限時のチャンクごとの再試行回数
SHUNT_CHUNK_RETRY_DELAY	60	プロバイダーのクォータ枠（無料枠のTPM）がリセットされるまで待機する秒数

---

モード2：PreToolUseインターセプターフック

実行前フックに対応するエージェント（例：Claude Code、カスタムのエージェントループ）向けです。

1. ファイル読み取りインターセプター（check-file-size）：
   • エージェントがしきい値を超えるファイル全体を読み取ろうとした場合（デフォルト：350行、SHUNT_MIN_LINESで設定可能）、フックは呼び出しをブロックし、bulk-readに委任するようエージェントに指示します。
   • offsetとlimitを指定した対象範囲の読み取りは許可されるため、コード編集に必要な部分だけをコンテキストに取り込めます。
2. ターミナルガード（check-bash-read）：
   • エージェントがターミナル上で大容量ファイルに対してcat、less、moreなどのコマンドを直接実行し、読み取りフックを回避することを防ぎます。

---

モード 3：スタンドアロン CLI とスクリプト

Model-Shunt は、コマンドラインやエージェントの bash セッションから直接使用することもできます。

利用可能なモデルと推奨事項を確認する

python3 src/model_shunt/worker.py --list-models --provider gemini

一括読み取り分析を実行する

./plugin/scripts/bulk-read \
  --question "How does the token refresh cycle work?" \
  --paths src/auth.py src/tokens.py \
  --auto-model

ボイラープレートをディスクに直接生成する

./plugin/scripts/code-write \
  --spec "Create unit tests for the BillingService covering charge and refund" \
  --reference tests/test_user.py \
  --target tests/test_billing.py \
  --auto-model

---

🧪 検証

組み込みのテストスイートを実行して、環境を検証します。

python3 test_shunt.py

テストスイートでは、以下を検証します。

• 設定の解決、フォールバックの連鎖、モデルの選択。
• バイナリファイルの検出と拒否。
• フックの判定（限定的な読み取りは許可、大きなファイルの読み取りはブロック、bash フラグの解析）。
• MCP の stdio プロトコルへの準拠とツールの実行。
• CLI の検出フラグ。

---

📄 ライセンス

MIT。Spotify Engineering の Shunt アーキテクチャに着想を得ています。

🔒 プライバシー

ファイルシステムの範囲、プロバイダーデータの取り扱い、認証情報の管理方法については、PRIVACY.md を参照してください。