Nanako0129/pilotfish

pilotfish – Claude Codeエージェントのオーケストレーション

何であるか

• Claude Code（Anthropicのコーディングアシスタント）がプログラミングセッションを複数の軽量な「ロールエージェント」に分割できるポリシー・パッケージ。
• 各ロールはコストと能力に応じて異なるClaudeモデル（Opus、Sonnet、Haiku）で実行され、メインセッションは高レベルな計画と判断に集中し、安価なモデルが繰り返し作業や低リスク作業を処理する。

なぜ重要か

• 長時間のコーディングセッションでは、コアな設計意思決定よりも検索、リファクタリング、テスト、ドキュメント作成に多くのトークンが使われる。
• pilotfishはこれらの限定されたタスクを自動的に安価なモデルにルーティングし、トークンコストを削減するとともに、メインモデルが前線の推論と最終承認に集中できるようにする。

仕組み

1. インストール – いずれかの プラグイン（macOS/Linux）または レガシーグローバル インストール（~/.claude/ またはカスタム CLAUDE_CONFIG_DIR 下にファイルを書き込む）。
2. ポリシー・ファイル –
   • settings.json はメインモデルのエイリアス（Opusファミリー）とフォールバックチェーンを定義。
   • agents/*.md は各ロール（例：scout、mech-executor、security-reviewer）を記述。
   • CLAUDE.md は、作業をメインセッションで保持するかロールに委任するかを決定するディスパッチロジックを含む。
3. ディスパッチフロー – Claudeと対話する際、pilotfishは インタラクションの形状（例：co_discover、explore_then_plan、execute）を検査。形状に応じて、以下のように処理する可能性がある：
   • リポジトリ調査のために低コストの scout（Haiku）を呼び出す。
   • 提案された計画を検証するための plan-verifier（Opus）を使用。
   • 機械的な繰り返し作業を mech-executor（Sonnet）に委任、または承認後に高リスクコードを executor（Sonnet）に委任。
   • 実装後に結果を反証するための verifier（新規Opusコンテキスト）を実行。
   • セキュリティ関連の作業を security-reviewer および security-executor（両方Opus、読み取り専用→高負荷）を経由してルーティング。
4. ポリシーは CLAUDE.md 内のマーカー（pilotfish:begin/end）で記述されており、Claudeは各セッションで読み込むため、動作が自動的に適用される。

インストール手順（概要）

• プラグインベータ – install/PLUGIN-INSTALL.md を参照。macOS（Claude Code 2.1.239）およびLinux（Ubuntu 20.04+、Debian 10+、Alpine 3.19+）対応。Claude Code 2.1.219+が必要。プラグインは唯一のインストール（レガシーグローバルインストールと併存不可）。
• レガシーグローバル – タグ付きリリースでリポジトリをクローンし、claude を実行して install/AGENT-INSTALL.md のランブックに従う。インストーラはマージ計画を表示し、既存ファイルをバックアップ、再実行可能（idempotent）。

システムの運用

• 同じインストールガイドを使ってプラグインの有効/無効切り替えや更新。
• docs/usage.md でモデル選択、作業負荷、委任ルールを調整。
• セッションでpilotfishを有効化するには、提供された /pilotfish コマンド、または install/ACTIVATION-INSTALL.md に記載のCLIラッパーを実行。
• Claudeにアンインストールランブックを実行させることで安全にアンインストール可能。8つのエージェントファイルとポリシー・ブロックが削除される。

証拠と研究

• リポジトリには設計ノート、経済分析、フィールドレポート（docs/design.md、docs/research.md）が含まれる。
• spontaneous-dispatch や dispatch-brake といったベンチマークにより、委任がどの程度発生するかの行動観察が可能。

誰が使うべきか

• Claude Codeで長時間作業する開発者で、トークンコストを下げたい人。
• 低リスクの自動化と高リスクの判断を再現可能でポリシー駆動で分離したいチーム。
• マルチモデルオーケストレーションやリスク意識型AIアシスタンスに興味のある研究者。

ライセンスとサポート

• MITライセンス。
• 著者は、有料モデルの検証実行を資金化するため、Patreonによるスポンサーシップを歓迎している。

---

すべての詳細はリポジトリのREADMEから直接引用；追加機能は推測しない。