Harmonist：IDE フックでプロトコル遵守を強制する 193 エージェント構成
Portable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.
ひと目でわかる
- これは何？
- README が示すのは、プロンプトでお願いするのではなく stop フックでターンを完了させないという設計。186 あるいは 193 というエージェント数の表記揺れと、stdlib のみという制約を軸に、採用判断に必要な情報を整理する。
- 誰に向いている？
- 導入を検討すべきなのは、Cursor や Claude Code を日常的に使い、レビュー手順や記憶更新をモデルの善意に任せたくない個人開発者や小規模チームである。逆に、独自のオーケストレーション層をすでに持ち、フックの実行順序を自分で制御したい場合や、Python 3.9 未満の環境しかない場合は向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 98 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
プロンプトで守らせていた規約を、フックで止める
このプロジェクトが解こうとしている問題は、規約違反そのものではなく、規約違反が検出されないまま出荷されることである。README は「no floating-point for money」「run QA before merging」「security review before touching auth code」のような非交渉のルールを例に挙げ、LLM は指示されれば同意できるが、そのステップを静かに飛ばす機構上の歯止めがないと述べている。Harmonist の立場は、規約をプロンプト内の依頼として書くのではなく、IDE のフックとして実装するというものだ。対象読者は Cursor、Claude Code、Copilot、Windsurf、Aider といったコーディングアシスタントをすでに使っている開発者で、レビュー工程を人手で回すほど人数がいないか、回しているつもりが抜けているケースを問題視している層になる。README は既存の選択肢を二つに分け、LangChain、CrewAI、AutoGen、MetaGPT などを「orchestration primitives を提供するが強制はプロンプト任せ」とし、企業向け基盤は別ランタイムとデータベースを要求してノート PC で動かないと整理している。この二分法はやや粗いが、少なくとも Harmonist 自身がどの位置を取りたいかは明確である。
stop フックが followup_message を返してターンを閉じさせない
機構の中心は .cursor/hooks/ に置かれた stop フックである。README によれば、このフックはセッションからサブエージェントの dispatch マーカーを解析し、qa-verifier が実行されたか、必須のレビュアーが欠けていないか、session-handoff.md が更新されたかを確認する。条件を満たさない場合、構造化された followup_message を AI に返し、ターンの完了を許可しない。再試行は loop_limit: 3 で上限が切られ、上限に達するとインシデントが記録され、次のセッションで表面化する。ここで重要なのは、判定がモデルの自己申告ではなくディスク上の状態機械として行われる点だ。README の表現を借りれば「it's a state machine on disk」であり、モデルが完了したと主張しても、フックが満たされていなければターンは閉じない。あわせて memory.py append が唯一の書き込み経路として指定され、memory/SCHEMA.md の YAML スキーマに対する検証、重複の拒否、本文の秘密情報スキャンを行う。スキャン対象は AWS アクセスキー、GitHub PAT、Stripe トークン、Slack webhook、GCP サービスアカウント、Azure 接続文字列、Telegram ボットトークン、Discord トークン、Heroku と Postmark の UUID（文脈依存）、secret: 接頭辞付きの高エントロピートークン、資格情報を埋め込んだ DB 接続文字列で、約 30 種とされている。${VAR} や <NAME> のようなプレースホルダはスキャンを抑制する。
correlation_id をモデルに書かせない設計
記憶の整合性について、Harmonist はモデルを信用しない立場をはっきり取っている。各メモリエントリには <session_id>-<task_seq> 形式の correlation_id が付くが、これはセッション開始時にフックが生成する。README では <unix-seconds><pid4> と説明され、並列セッション間での衝突を避ける意図が読み取れる。LLM は CLI 経由で現在の ID を読むだけで、自分で書くことはない。同じタスクに由来する state エントリ、decision、pattern の対応関係は、フックの視点では順序付けられており、モデルの記憶に依存しない。ここで注意したいのは、README が「cryptographically ordered」という語を使っている点だ。実際に読める限りでは、これは ID の生成元がフックであり、モデルが関与しないという意味での順序保証であって、暗号学的な証明を伴うものかは README からは判断できない。表現がやや強めである。とはいえ、ID の生成元をモデルの外に置くという発想自体は、監査可能性を上げる方向に働く。
MANIFEST.sha256 が upgrade 前に改ざんを拒む
供給網の検証は MANIFEST.sha256 を基準に行われる。agents/、hooks/、memory/、playbooks/、ルート文書といった実行時に出荷される内容がハッシュ化され、CI 設定とリポジトリのメタデータはパックリポジトリ専用として除外される。upgrade.py はプロジェクトへコピーする前に各ソースを sha 検証する。README の例では、常に approve を返すように書き換えられた security-reviewer.md のような改ざんは拒否され、プロジェクトに入らない。install_extras.py もオンデマンドの specialist 導入時に同じガードを継承する。この仕組みが効くのは、エージェント定義がプロンプトの集合ではなくファイルとして配布される場合に限られる。逆に言えば、利用者が自分のプロジェクトでエージェント定義を直接編集する運用にすると、マニフェストとの整合は当然ながら崩れる。カタログを固定物として扱い、カスタマイズは別レイヤで行う前提の設計だと読める。
導入手順と、stdlib のみという制約の意味
README は冒頭で、AI エージェントがこのパックを導入する場合は integration-prompt.md を読み、その手順を実行するよう指示している。同時に、AGENTS.template.md をパックフォルダ内の生きたルールとして適用してはならないと明記する。これは統合時にユーザープロジェクトの AGENTS.md へ展開されるテンプレートだからだ。requirements は Python 3.9+ と stdlib のみで、ランタイムもデータベースも要求しない。Python 3.9 という下限は、古いディストリビューションの標準 Python では動かない可能性を意味する。エージェントのカタログは agents/index.json にあり、README のバッジは 193 と表示する一方、リポジトリの説明文と本文の見出しには 186 と 193 の両方が現れる。ここは採用前に自分で index.json を数えて確認する価値がある。CI は .github/workflows/ci.yml で、README はテスト数を 550+ とする。ライセンスは MIT で、改変と再配布の条件は比較的緩い。ただし、エージェント定義やフックを改変して再配布する場合、MANIFEST.sha256 との整合をどう取るかは各自の運用判断になる。
フックが効かない場所では意味を失う
この設計の限界は、強制がフックの実行に依存している点に集約される。stop フックが動かない IDE、あるいはフックを無効化したセッションでは、判定は行われず、規約は単なる文書に戻る。README が挙げる対応先は Cursor、Claude Code、Copilot、Windsurf、Aider などだが、各 IDE でフックの仕組みが同じように存在するかは README からは読み取れない。.cursor/hooks/ というパスが例示されている以上、少なくとも Cursor 前提の記述が濃い。また、loop_limit: 3 で再試行が打ち切られるとインシデント記録に移るため、フックの条件が厳しすぎるプロジェクトでは、完了できないターンが繰り返し記録されることになる。フックの条件そのものを緩めれば強制力は落ちる。この二律背反は設計上のトレードオフであり、README はどちらに倒すべきかについては触れていない。さらに、メモリの書き込みが memory.py append に一本化されている以上、この CLI を経由しない既存のメモ運用があるプロジェクトでは、移行か併用かの判断が必要になる。
LangChain 系との違いは強制の所在
比較対象として README が名指しするのは LangChain、CrewAI、AutoGen、MetaGPT である。これらはオーケストレーションのプリミティブを提供するが、規約の遵守はプロンプトに委ねられ、モデルが自分のプロトコルを上書きできる。Harmonist の違いは、強制の所在をモデルの外、つまり IDE のフックとディスク上のマニフェストに移したことにある。同じ「マルチエージェント」という語を使っていても、問うている問いが違う。LangChain 系はどう組み合わせるかを扱い、Harmonist はどう守らせるかを扱う。だから両者は排他的ではなく、Harmonist のフックが呼び出す先に別のオーケストレータを置くことも理屈上は可能だろう。ただし README はその併用について何も述べていない。エージェント数 193 という規模は、役割を細分化してレビュー工程を分担させる前提であり、少数の汎用エージェントで足りる小規模な作業では、カタログの大部分が使われないまま残る。
採用前に数えるべきもの
向いているのは、Cursor を主軸に使い、レビューと記憶更新の抜けを機械的に検出したい個人開発者か小規模チームである。向かないのは、フックの実行順序を自分で設計したい場合、Python 3.9 を用意できない環境、あるいはエージェント定義を頻繁に書き換える運用をすでに持っている場合だ。最初に確認するのは三点ある。agents/index.json を開いて実際のエージェント数を数えること。integration-prompt.md の手順を読み、AGENTS.md がどのパスに生成されるかを確認すること。そして .cursor/hooks/ の stop フックが自分の IDE で発火するかを、コード変更を伴わないターンで試すこと。README の説明とリポジトリの記述には 186 と 193 の揺れがあり、この種の不一致は導入後の挙動確認で最初に突き当たる場所でもある。
編集部の結論
導入を検討すべきなのは、Cursor や Claude Code を日常的に使い、レビュー手順や記憶更新をモデルの善意に任せたくない個人開発者や小規模チームである。逆に、独自のオーケストレーション層をすでに持ち、フックの実行順序を自分で制御したい場合や、Python 3.9 未満の環境しかない場合は向かない。最初に確認すべきは、README 内でエージェント数が 186 と 193 で食い違っている点がどちらの記述に由来するか、そして integration-prompt.md を実行したあと AGENTS.md がどのパスに生成されるかである。
コミュニティノート