連載：複数の AI を率いる司令塔「vicara」の裏側

第1弾：概要・思想編

第2弾：技術深掘り編（本記事）

[第3弾：徹底比較編]（予定）

前回の記事では、AI コーディングエージェントを軍団として統制する「vicara」の思想についてお話ししました。

第2弾となる今回は、その「司令塔」の裏側で、具体的にどのような技術が動いているのか、そして Windows 環境での実装においていかに泥臭い苦労があったか をお話しします。

正直に白状します。
実装している最中、私は自分のコードが「Windows という名の魔境」の深淵に触れていることに気づいていませんでした。
それらはすべて、私が率いていたはずの AI エージェントたちが、私の知らないところで戦い、解決してくれていたことだったのです。

1. アーキテクチャ概要：司令塔となる Rust バックエンド

vicara のコアエンジンは、Rust で書かれたバックエンドです。Tauri v2 をベースに構築されており、フロントエンド（React）からの指令を受けて、複数の AI CLI（Claude Code, Gemini CLI 等）を並列に動かします。

司令塔の主な役割は以下の3つです：

Runner 抽象化: 異なる AI CLI の引数や出力を統一的に扱う。
PTY 制御: ターミナルをアプリ内に統合し、対話型 CLI を遠隔操作する。
Git Worktree 管理: 物理的に分離された安全な作業空間を即座に提供する。

(余談) AI が提案した「自分の名前」
ちなみに、開発中に AI に「このバックエンドに相応しいコードネームを付けて」と相談したところ、司令塔としての役割から Viceroy（総督） はどうか、と提案されました。今のところ正式名称ではありませんが、AI が自らに付けたこの名前、司令塔としての自負が感じられて個人的には気に入っています。

一見シンプルに見えるこれら 3 つですが、Windows という環境が立ちはだかることで、実装は一気に牙を剥きました。

2. PTY の深淵：Windows ConPTY との死闘

AI エージェント（Claude Code 等）は、多くの場合ターミナル上で人間と対話することを前提とした CLI です。これを GUI アプリから制御するには、PTY（擬似端末） を偽装して「エージェントを騙す」必要があります。

Unix 系であれば forkpty という枯れた技術がありますが、Windows はそうはいきません。

ConPTY の壁

Windows では ConPTY (Windows Pseudo Console) という比較的新しい API を叩く必要があります。vicara では Rust の portable-pty クレートを使用していますが、そこで直面したのは以下のような問題でした。

文字化けの猛攻: Windows のターミナルエンコーディングは歴史的な経緯が複雑です。UTF-8 で出力される AI エージェントのログをそのまま流すと、日本語や色付けのエスケープシーケンスが化け、UI が崩壊します。
対策: chcp 65001 を強制した上で、Rust 側でストリームをバッファリングし、壊れたマルチバイト文字を適切に再構成するロジックを組み込みました。
ゾンビプロセスの撲滅: ユーザーがタスクを中断した際、親プロセス（CLI）は死んでも、その中で動いていたビルドプロセスが生き残ってしまう。Windows でプロセスツリー全体を確実に「殺し切る」実装は、想像以上に泥臭いコードになりました。

ここでの驚きは、私が「ターミナルってどう繋ぐんだっけ？」と AI に聞いた時、AI がこれらの Windows 特有の罠を考慮した Rust コードをさらっと提示してきたことです。彼らは自分の「安住の地」を確保するために、自ら茨の道を切り拓いていたのです。

3. 三者三様の CLI：彼らの「個性」を手なずける

vicara は Claude Code だけでなく、Gemini CLI や Codex CLI にも対応していますが、彼らの性格（引数仕様）は驚くほどバラバラです。

異なる「魔法の言葉」

AI エージェントを非対話形式で動かすには、「勝手に進めていいよ」という承認フラグを渡す必要がありますが、これが三者三様です。

Claude: --permission-mode bypassPermissions （とても丁寧）
Gemini: --yolo （You Only Live Once... 勢いがすごい）
Codex: サブコマンド exec --full-auto （無機質な感じ）

Windows npm shim の罠

Windows で gemini コマンドを叩くと、実際には .cmd というバッチファイルが動きます。これを PTY で直接叩くと中断操作が効かないなどの問題が起きるため、vicara のバックエンドは、コマンドのパスから node_modules を逆引きして、直接 node.exe で JS ファイルを叩く という執念深い回避策を自動で行っています。

4. Git Worktree とコンフリクト：執念のリセットと継続

vicara の最大の特徴は、タスクごとに git worktree を使って作業空間を物理的に隔離することです。

node_modules 容量爆発問題

各ワークツリーで npm install が走ればディスクが溶けます。vicara は 「まずシンボリックリンクを試み、失敗したらジャンクションにフォールバック」 という三段構えで node_modules を共有します。AI が「Windows ならジャンクションを使いましょう」と提案してきたときは、その知識の深さに驚かされました。

コンフリクト発生時の「即時撤退」と再挑戦

並列実行でコンフリクトが起きた際、vicara は git merge --abort で即座に撤退します。

面白いのはその後の「再実行」の仕組みです。一度競合して汚れたワークツリーは、中途半端に直すよりも 「物理的に一度削除し、クリーンな状態で最新の main から作り直す」 というリセット戦略をとります。

記憶（コンテキスト）は additional_context として AI に引き継ぎつつ、環境（ファイルシステム）は常に清廉潔白に保つ。この安定性を重視した「リセット＆継続」のロジックこそが、軍団を崩壊させないための要諦です。

5. まとめ：泥臭い低レイヤを AI に任せる未来

今回紹介した PTY や Git の苦労は、本来なら私一人が一週間頭を抱えて実装するような内容でした。しかし、AI エージェントという「軍団」を指揮していたことで、私は課題を提示するだけで、彼らが勝手に戦い、最適な（そして非常に泥臭い）解決策を持ってきてくれました。

「一人の人間が、AI という軍団を率いて、自分一人では到達できない実装精度に到達する」

これこそが、vicara が目指す「将軍（ユーザー）」としての開発体験です。

次回予告

第 3 弾では、話題の Claude Code や Devin, OpenHands と vicara はどう違うのか？どう使い分けるのが最強なのか？について、忖度なしで徹底比較したいと思います。

ぜひ、また戦場（Qiita）でお会いしましょう！

🔗 GitHub: https://github.com/ytakahashi0302-ghb/ai_scrum_tool
（開発を応援いただける将軍は、ぜひ Star で援護をお願いします！）