magi — Chat で頼むだけで、設計・実装・レビュー・PR・リリースまで複数のエージェントがつないでくれる CLI

claude や codex といったエージェント CLI を複数使って、頼んだ作業を設計からリリースまで進めてもらうツール magi を Rust で作りました。人間がやることは、基本的に Chat で頼むことと、聞かれたことに答えること、最後にマージを承認することです。
なぜ作ったのか
エージェントに実装を任せられるようになっても、その前後は意外と人間がつないでいます。
- 頼む前に、何を作るかが曖昧なまま投げると、出てきたものの良し悪しも判断できない。
- 最初の設計方針が一本だけだと、それが外れていたときにレビューで直しきれない。レビューの観点も、1 人のエージェントでは偏る。
- PR を作る、CI を見る、指摘に対応する、リリースの version を上げる、といった PR からあとの作業を、結局自分で見張っている。
- 離席中にエージェントが判断に迷って止まっていても、PC の前にいないと気づけない。
これらを「頼んだら、あとは必要なときだけ呼ばれる」形にしたくて作ったのが magi です。subscription 契約の CLI(claude / codex / opencode / agy / omp、または任意のコマンド)をそのまま動かす仕組みなので、既存のプランの範囲で動き、API キーは要りません。
magi の主な特徴
以降の説明には、magi.toml の設定名が出てきます。magi.toml は TOML で書く設定ファイルで、[graph](実装・レビュー・マージまでの流れ)、[verify](検証に使うコマンド)、[merge] と [release](マージ後とリリースの扱い)といったセクションに分かれています。記事では [graph] implementers のように「セクション名 + キー名」で書きます。実際に触るのは、magi init が書き出す magi.toml です。
1. 頼むのは Chat だけ
magi web で起動するスマホ向けの UI に Chat があります。リポジトリを読んだりコマンドを実行したりできるエージェントと、作りたいものを相談します。やりたいことの形が固まったら「タスクとして登録して」と伝えると、エージェントが会話の中から magi task add --solo(単独実装)を実行してくれます。会話ごとに、2〜3 人の implementers で競わせる設定へ切り替えることもできます。
- 会話は Chat のまま続くので、あとから別の作業を頼めます。
- Chat は既定では書き込み禁止で動きます(会話の途中でリポジトリが変わると、あとの比較ができなくなるため)。
登録されたタスクは magi serve / magi web のループが 1 つずつ取り出して実行します。magi web のループは、スマホの UI からそのまま開始・停止できます。ターミナルから magi run "add retries to the uploader" のように直接頼むこともできます。
2. advisors が設計を出し、synthesizer が 1 本にまとめる
実装の前に advise という段階があります。
- advisors(既定 3 人)が、それぞれ read-only で設計案を出します。
- synthesizer が、その案の良いところを混ぜて 1 つの設計方針にまとめます。
synthesizer は、各案の良い部分を 1 本の方針に統合します。どれが勝つかは決めません。実装者にはこの方針が渡ります。[graph] advise で on / off できます。
3. implementers が実装し、judges が投票する
方針をもとに implementers が実装します。競争モードで複数の implementers を動かすと、候補は A / B / C のようにラベル化され、judges が順位を付け、意見が割れれば議論したうえで投票します。
なお、[graph] implementers の既定値は 1 です。ただし magi init が書き出す magi.toml には 3 と書かれているので、そのまま使うと 3 人で競います。人数は magi run --implementers N(短縮形 -c)や [graph] implementers で変えられます。Chat では、会話ごとのセレクトで Solo / 2 / 3 を選べます。
4. reviewers と fixer のレビューループ
実装を勝ち残らせたら、次は有限回のレビューループです。
- 各 reviewer には、レビュー対象のコミットに固定された専用の detached worktree が渡されます。レビュー中に作業ツリーが変わることはなく、fixer と競合もしません。
[verify] e2eに書いたコマンドが worktree で実行され、その出力が fixer に渡されます。- fixer が blocking な指摘を直します。ただし、確認できる根拠があれば、指摘を根拠つきで却下することもできます。
- 指摘がなくなり検証も通るか、
[graph] review_roundsで決めた回数を使い切るまで繰り返します。
finding の id(R2-1-3 のような形式)はエージェントではなく magi が振ります。fixer の対応報告をこの id で突き合わせられるので、reviewer の精度を集計して確かめられます。また、タイムアウトなどで reviewer が答えなかったラウンドは「指摘なし」とは見なされません。
5. PR・gate・e2e・リリースまでを通す
merge = "pr" のときは、実装の最後に magi が PR を開き、そのまま見張り続けます。
- CI の結果と、人間・bot 双方のレビューコメントを読み、必要なら fix ラウンドを回して push します。
[graph] land(既定 on)の領域です。 - マージ前には
[verify] gateに書いたコマンドがすべて exit 0 になる必要があります。gateを CI と同じコマンドにしておけば、ローカルで通れば PR も緑になります。 - 強制マージはしません。ラウンドを使い切ったら、何が失敗しているかをコメントして PR を開いたままにします。
マージが済んだあとのリリースにも関わります。Rust リポジトリ(base ブランチのルートに Cargo.toml がある場合。ない場合はスキップ)では、[merge] release_bump(既定 on)により、変更内容から major / minor / patch のどの桁を上げるかを magi が判断し、chore/release-vX.Y.Z という version bump の PR を開きます。どのリポジトリでも公開まで進むわけではありません。その先は [release] mode で分かれます。
actionsモード(既定)では、version bump の PR は automerge が設定され、CI が通ればそのままマージされます。つまりこの PR には、実装 PR のような個別の承認の質問は付きません。マージ後のタグ付けと公開は、リポジトリ側の GitHub Actions に任せます。たとえば私のリポジトリでは、version が上がったマージを検知してタグを push する workflow と、そのタグで公開する workflow を置いています。この構成ではタグを打つのは magi ではありません。localモードは、Actions が動かないリポジトリ向けの opt-in です。automerge は設定されず、リリース PR のマージも所有者の承認(merge/holdの質問)を待ちます。承認されてマージされたあとは、magi 自身がタグを作って push し、[release] commandsに書いたコマンド(cargo build --releaseやgh release createなど)を順に実行して公開します。
6. 分からないときは Question で聞かれる。マージは承認が先
途中で判断に迷ったエージェントは、推測で進めずに質問します。
magi ask --summary "Which storage backend?" --choice SQLite --choice Redisこれはエージェントが実行するコマンドで、答えが来るまで止まります。質問はスマホの UI に選択肢のボタンつきで表示され、押した答えがそのままエージェントの標準出力に返ります。ターミナルでは magi answer で同じ答えを返せます。質問には HTML で書いた確認画面(Panel)も添えられるので、diff や表を見ながら決められます。

実装した変更の PR のマージも同じ仕組みです。[graph] land_approval は既定で on で、マージ前に「何が入るか」を並べた質問が来ます。沈黙は保留として扱われ、何も答えなければマージされません。上で書いたとおり、actions モードの version bump PR だけは、CI が通れば自動でマージされます。無人でマージさせたい場合は、land と land_approval の両方を意図して切り替えます。既定では、実装した変更の最後の一歩は人が決めます。
インストールと使い方
インストール
cargo install magi-cliクイックスタート
magi init # 最初の magi.toml を書き出す
magi doctor # CLI やリポジトリ、使うエージェントの確認
magi web # スマホ向け UI を起動するmagi web を開いたら、画面の「Start the loop」を押してループを動かします。あとは Chat でタスクを頼むだけです。画面を開かずにキューだけを回したいときは magi serve を使います。同じキューのループは、magi web と magi serve のどちらか一方で回します。
[verify] gate と [verify] e2e は、そのリポジトリで実際に確認したいコマンドに合わせて magi.toml に書きます。
どこで起動するか
magi web と magi serve は、--repo を付けなければ、起動したディレクトリを「リポジトリを指定しなかったタスクの対象」にします。Chat の最初の会話も、このリポジトリで始まります。1 つのリポジトリだけで使うなら、そのリポジトリのルートで起動して、ルートの magi.toml を使えば十分です。
複数のリポジトリで使うなら、リポジトリではないディレクトリ(私はホーム)から起動して、グローバルの設定ファイルに [repos] roots を書く運用が楽です。
[repos]
roots = ['{{ home() }}/src'] # <root>/<host>/<owner>/<repo> の形で並んだチェックアウトを探す~ は展開されないので、設定ファイルのテンプレートで使える {{ home() }} でホームを指します。Windows のパスにも対応できるよう、引用符は一重(TOML のリテラル文字列)にします。
Chat では「owner/repo に〜を足して」と頼むと、エージェントが magi task add --repo owner/repo でタスクを出します。repo 名だけでも、一意に決まれば通ります。名前は roots 以下のチェックアウトから解決され、一覧は magi repos で見られます。gate などの検証コマンドは、各リポジトリの magi.toml に書いたものが使われます。
設定ファイルの置き場所
設定は 3 か所に分けて書けます。下に行くほど優先されます。
<config_dir>/magi/config.toml # マシン共通(グローバル)
<repo>/.magi/config.toml
<repo>/magi.toml # リポジトリごと<config_dir> は OS 標準の設定ディレクトリで、macOS なら ~/Library/Application Support、Linux なら ~/.config です。環境変数 MAGI_CONFIG_DIR で置き場所を変えられ、空文字にするとマシン共通の層は読まれません。
分けている理由は、使えるエージェントの一覧(どの CLI を、どのモデルで使うか。[[agents]] に書きます)と、implementers / judges / reviewers などの役割の割り当てはマシンごとの事情で、gate はリポジトリごとの事情だからです。前者は <config_dir>/magi/config.toml に 1 回だけ書き、各リポジトリの magi.toml にはそのリポジトリ固有の [verify] gate などだけを書けます。
グローバルの設定ファイルは必須ではありません。magi init が書き出す magi.toml には、PATH から検出した CLI が [[agents]] として入っているので、それだけで動きます。設定が何もない場合も、PATH 上にあるエージェント CLI をそのまま使います。
magi web の Settings 画面で、エージェントの割り当てや人数を保存すると、このグローバルの設定ファイルが作られます。
implementers のような配列は、複数の場所に書くとエラーになります。マージで足し合わされて、頼んでいない構成になるのを防ぐためです。マシン側かリポジトリ側の、どちらか 1 か所だけに書きます。実際にどう解決されたかは magi doctor で確認できます。
設定ファイルの例
私の設定から、抜粋して載せます。まずグローバルの設定です。使うエージェント、役割の割り当て、実行の流れ、マージの方式をここに置いています。
# <config_dir>/magi/config.toml
[[agents]]
id = "opus"
kind = "claude"
model = "claude-opus-5-5"
extra_args = ["--effort", "medium"]
[[agents]]
id = "sonnet"
kind = "claude"
model = "claude-sonnet-5-5"
extra_args = ["--effort", "medium"]
[[agents]]
id = "sol"
kind = "codex"
model = "gpt-6.1-sol"
extra_args = ["-c", "model_reasoning_effort=\"medium\""]
[roles]
# 先頭から順に担当し、[graph] の人数を超えた分は、quota 切れや失敗のときの予備になる
implementers = ["sonnet", "sol", "opus"]
judges = ["opus", "sol", "sonnet"]
reviewers = ["sol", "opus", "sonnet"]
[graph]
implementers = 2
judges = 3
reviewers = 2
review_rounds = 3
language = "ja" # エージェントが書く言語。コードとコメントは英語のまま
[merge]
base = "main"
mode = "pr" # ブランチを push して PR を開く
[repos]
roots = ['{{ home() }}/src']次に、リポジトリごとの設定です。magi 自身のリポジトリの magi.toml から抜粋しています(magi は magi で開発しています)。使うエージェントや役割の割り当ては書かず、このリポジトリに固有のことだけを書きます。
# <repo>/magi.toml
[verify]
e2e = ["cargo test --locked --all-targets"]
gate = ["cargo make check"]
pre_gate = ["cargo fmt --all"] # gate の直前に、勝った実装だけに実行する
[merge]
base = "main"
style = "squash" # マージコミットを禁止している ruleset に合わせる
[prompts]
all = """
Full verification is parent-owned: magi runs `cargo test --locked --all-targets` and `cargo make check` itself. Do not re-run the full suite or the full gate yourself; a focused `cargo check` or a targeted `cargo test <name>` is enough.
"""
review = """
Formatting is not a finding: `cargo fmt` runs in the gate. Spend the round on correctness and on invariants the code claims and does not keep.
"""[prompts] は、このリポジトリで動くエージェントに渡す、プロジェクト固有の前提です。all は全員に、review は reviewer にだけ渡ります。
おわりに
自分にとって一番大きいのは、「頼む」と「承認する」の間を自分で埋めなくてよくなったことです。判断が必要なところだけスマホに通知が来て、それ以外は進んでいます。
今回は Chat・設計の統合・レビューループ・リリースまでの流れを中心に紹介しました。judges の評価の仕組みなど、ここで触れていない部分は README にまとまっています。