professorpalmer/Puppetmaster

Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.

Puppetmaster – LLMベースの開発エージェントのための永続的なオーケストレーション

概要 – puppetmaster（PyPIからpuppetmaster‑aiとしてインストール）は、Pythonベースのスーパーバイザーで、既に使用しているLLM搭載ツール（Cursor、Claude‑Code、Codex、Gemini Antigravity、Hermes、OpenAI互換APIなど）を通じてマルチステップのエンジニアリングタスクを実行できます。独立したワーカープロセスを起動し、各サブタスクを最適なモデルにルーティングし、すべての型付き結果をローカルのSQLiteデータベースに永続化します。保存された成果物により、ワークフロー全体を検査可能、再開可能、監査可能にします。

重要性 – 一般的なLLM「エージェント」は単一の成長するトランスクリプトを保持するため、障害からの回復、モデル出力の比較、実行内容の証明が困難です。Puppetmasterは作業を永続的な型付き成果物に分割し、開発者にコードベース監査、リファクタリング、またはリポジトリ全体の自動化のための信頼性の高い状態レイヤーを提供します。

コアコンセプト

コンセプト	役割
Pilots (MCP)	Puppetmasterを呼び出すフロントエンド（Cursor Agent、Grok Bot、Claude Desktop、Pi、OMP）。
Adapters / Workers	具体的なモデルバックエンド（cursor、claude‑code、codex、hermes、antigravity、汎用agentic API）。
Supervisor	ルーティングを調整し、ワーカーを起動し、SQLite成果物を書き込み、統合サマリーを提供します。
SQLite store	各ステップの永続的なログ（ペイロード、証拠、コンテンツハッシュ）で、後でクエリ可能。
Dashboard	ライブジョブ検査用の小さなWeb UI（`http://127.0.0.1:<port>/?job=<id>&embed=1`）。スマートフォンからも使用可能。

クイックスタート（シェル）

# インストール（pipx推奨）
pipx install puppetmaster-ai
# 使用するアダプターを設定（例：Cursor）
puppetmaster setup --platforms cursor

# 現在のリポジトリで簡単な「doctor」パスを実行
puppetmaster doctor

# 監視付き変更を起動
puppetmaster start "Review this repo for release blockers" \
    --review --dry-run

# 最新のジョブを検査
puppetmaster show $(puppetmaster last)

サポートされているUI（Cursor、Grok Botなど）では、次のように入力するだけです：

Use Puppetmaster to run doctor in this repo and summarize what is missing.

UIはリクエストをローカルのスーパーバイザーに転送し、適切なワーカーを起動して、ポーリングできるジョブIDを返します。

主な機能

マルチモデルルーティング – サブタスクごとに最も安価または最も高性能なモデルを選択。コストルーティングによりSWE‑bench Liteで支出を約30%削減。
永続的な状態 – 各ワーカーは型付き成果物をSQLiteに書き込みます。ジョブはクラッシュ後も存続し、再開可能です。
ファンアウトとステッチング – 並列ワーカーを起動し、最終モデルが簡潔なサマリーを生成。
アダプター非依存 – MCPコントラクトに従う任意のCLIで動作（Cursor、Claude‑Code、Codex、Gemini Antigravity、Hermes、または汎用APIキー）。
Grok Bot用リモートMCP – 同じツールハンドラーをHTTP/SSE経由で公開し、CursorのGrok Botが別のマシンからジョブを駆動可能。
オプションのCodeGraphコンテキスト – codegraphインデックスが存在する場合、ワーカーは構造的なコード情報を自動的に受け取ります。
ダッシュボードとCLI検査 – puppetmaster artifacts <job_id> または python -m puppetmaster dashboard で生の結果を表示。
安全フック – 組み込みのリクエストレベル検証（puppetmaster setup --verify-first-run …）とSECURITY.mdに文書化されたセキュリティモデル。

証拠とベンチマーク

SWE‑bench Lite – 単一モデルのベースラインと比較して、実際の支出が29%削減、トークン一致で約48%の節約（シングルシード研究）。
NL2Repo‑Bench – 平均合格率91.1%、公開されている約40%のベースラインの約2.3倍。詳細な方法論はリンクされたベンチマークリポジトリと公開ブログ記事にあります。
再現可能なベンチマークスクリプトはリポジトリ（CLAIMS.md）に同梱されており、ルーティング、成果物の整合性、障害分類をカバーしています。

成熟度とライセンス

バージョン v1.27.8（ベータ、デイリードライバー）。最近のリリースでは、耐久性の修正、継続的プランニング、クロームフリーの埋め込みダッシュボードが追加されました。
インストール – pipxまたはpip。puppetmaster setupはアダプターとMCPフックの冪等なインストールを処理します。
アンインストール – puppetmaster uninstallはすべてのMCPエントリを削除します。状態は--purge‑stateでパージできます。
ライセンス – MIT。

使用時期

既に1つ以上のLLM搭載コーディングアシスタントを使用しており、それらを単一の場所で調整したい場合。
モデルが実行した内容の監査可能なログが必要な場合（例：セキュリティ監査、コンプライアンスチェック）。
ワークフローが並列モデル呼び出しと最終的な統合サマリーの恩恵を受ける場合。
単純なステップには安価なモデルをルーティングし、重要な編集には高価なモデルを予約してコストを削減したい場合。

詳細情報

完全なドキュメント：docs/README.md
アダプター設定の詳細：docs/ADAPTERS.md
機能マトリックス：docs/FEATURES.md
ベンチマークの主張：docs/CLAIMS.md
ダッシュボードの使用法：docs/DASHBOARD.md

結論 – Puppetmasterは、アドホックなLLMコーディングアシスタントを、組み込みのコストルーティング、耐久性、検査ツールを備えた信頼性の高いステートフルなエンジニアリングパイプラインに変える実用的なオープンソースレイヤーです。