ドキュメント

AgentMuxとは#

AgentMuxは、リモートホストと手元のPCで実行されるAIコーディングエージェント — Claude Code、Codex、 Gemini CLI、OpenCode、Aider、Cursor CLI — を運用するためのデスクトップアプリケーションです。 中核の仕組みは、一文で説明できます。

配布形態はシングルバイナリです。サーバーも、デーモンも、アカウントもありません。すべての状態は、 アプリケーションデータディレクトリ内のSQLiteファイル1つに収まります。各リモートホストへの接続は 多重化された1本のSSH接続で、ターミナル・コマンド・ファイル転送はその上のチャネルです。そのため、 1つのホストにターミナルを10枚開いても認証は1回だけ。アイドル状態の接続は10分後に閉じられます。

動作要件#

AgentMuxを実行するコンピュータ

管理対象ホスト

• リモートホスト：POSIXシェル、tmux、SSHアカウント。tmuxがなくても問題ありません — インストールパネルから導入できます。リモートのWindowsホストはサポートされません。
• 手元のPC（Linux / macOS）：ローカルのtmuxだけ — sshdも認証情報も不要です。
• 手元のPC（Windows）：同じマシンが2つのホストを提供します — デフォルトのWSLディストリビューション（tmuxが動く場所）と、ネイティブWindows（PowerShell、Windowsのパスとツールチェーン。MSVCビルドやWPF、ビルドしたばかりの.exeの実行に）。ネイティブセッションはAgentMux内蔵のセッションデーモンで永続化されるため、ウィンドウを閉じてもネイティブの作業は止まりません。

オプション：オーケストレーターとセマンティック検索

ローカルオーケストレーションとセマンティックメモリ検索には Ollama と、チャットモデル1つ・埋め込みモデル1つが必要です。Ollamaがなくても、他の機能はすべて利用できます。

インストール#

各リリースには、 タグ付きコミットからGitHub Actionsが生成したプラットフォームごとのビルドが1つずつ、 .sha256付きで用意されています。ビルドはまだコード署名・公証されていないため、 初回起動時に各プラットフォームで1回だけ追加の確認が必要です。

macOS

1. agentmux-macos-universal.zipをダウンロードして解凍し、AgentMux.appをアプリケーションフォルダにドラッグします。
2. 未署名ビルドに対するダイアログを、お使いのmacOSバージョンに応じて処理します（下表参照）。
3. 以降は通常どおり起動できます。

Windows

1. agentmux-windows-amd64.zipをダウンロードして解凍します — agentmux.exeとインストールスクリプトが含まれています。
2. ダブルクリックで実行し、SmartScreenが表示されたら詳細情報 → 実行を選択します。
3. 正式にインストールする場合（%LOCALAPPDATA%\Programs\AgentMuxへ配置、デスクトップとスタートメニューにショートカット作成、管理者権限は不要）は、解凍したフォルダで次を実行します。

powershell -ExecutionPolicy Bypass -File install-windows.ps1

同じスクリプトに-Uninstallを付けるとアンインストールされます。%APPDATA%\AgentMux内のデータには触れません。

Linux

1. まずランタイム依存をインストールします：Debian/Ubuntuではsudo apt install libwebkit2gtk-4.1-0、Fedoraではsudo dnf install webkit2gtk4.1。
2. agentmux-linux-amd64.tar.gzをダウンロードして展開します — バイナリ、アイコン、.desktopエントリ、install.shが含まれます。
3. ./install.shを実行するか、バイナリを直接起動します。

ダウンロードの検証

# すべてのファイルに.sha256が付属します:
shasum -a 256 -c agentmux-macos-universal.zip.sha256   # macOS
sha256sum -c agentmux-linux-amd64.tar.gz.sha256        # Linux

クイックスタート#

最初の管理対象エージェントまで4ステップです。ここで扱う操作はすべてCtrl/⌘ Kのコマンドパレットからも実行できます — あらゆる操作への最短経路です。

ステップ1：ホストを追加

リモートホストに必要なのは3つです。

• アドレスとユーザー — ssh user@hostで使うものと同じです。
• 3つの認証方式のいずれか：ssh-agent（推奨 — 入力不要）、鍵ファイル（パスフレーズ対応）、またはパスワード。
• ジャンプホスト（任意） — 踏み台サーバー越しの環境向け。

手元のPCに必要なのは名前だけです — sshdも認証情報も要りません。Windowsでは2つのローカルホストが 表示されます：WSLディストリビューションとネイティブWindowsです。ワークロードに応じて使い分けてください — UnixツールチェーンはWSLへ、MSVC/WPFはネイティブへ。

ステップ2：プロジェクトとワークスペースを追加

ワークスペースはホスト上の作業ディレクトリ（通常はリポジトリのルート）です。追加方法は2つあります。

• フォームから：ホストを選び、パスを入力します。
• ファイルブラウザから（速い）：ホストのファイルをブラウズし、目的のディレクトリを見つけて、その場で「プロジェクトとして追加」します — 名前・パス・ホストはすでに分かっています。

ステップ3：エージェントを追加して起動

エージェントは「名前」と「起動コマンド」の組み合わせです — ターミナルで打つのと同じコマンドを指定します。

# 典型的な起動コマンド。好みに合わせて調整してください
claude                    # Claude Code
codex                     # OpenAI Codex CLI
gemini                    # Gemini CLI
aider --model sonnet      # Aider
opencode                  # OpenCode

Startを押せば、ホスト上のtmux内で稼働が始まります。エージェントのAPIキーはホスト側 （エージェント自身の設定や環境変数）で設定します — AgentMuxはそれを読み取りもプロキシもしません。

ステップ4：アタッチして作業する

エージェントをクリックするか、Ctrl/⌘ Kで名前を検索します。そこにあるのは本物の ターミナルです — 色、マウス、選択、検索。いつでも割り込んで入力し、エージェントの軌道を修正し、 制御を戻せます — 再起動は不要です。サイドパネルには起動 / 停止 / 再起動 / アタッチの操作、 プロセスの状態、直近の出力が表示されます。

ターミナルウォール#

ターミナル領域は最大9ペイン（3×3）に分割でき、各ペインが独自のセッションを保持します — 1つのホストでも複数のホストでも、それぞれ独立して操作できます。

• ペインの追加：Ctrl/⌘ \。開いているタブの空きがあれば即座に分割され、なければホスト、ワークスペースのディレクトリ、実行中のエージェント、開いているタブから選ぶダイアログが表示されます。
• レイアウトは自動調整：ペインはピクセルではなく比率で領域を分け合います。読めないほど狭い列は畳まれるため、ウィンドウを狭めても3×3のウォールは9本の細切れではなく、縦長のグリッドに折り返されます。
• 境界をドラッグしてペインをリサイズします。
• 一時的なズーム：ペインのタブをダブルクリック（またはCtrl/⌘ ⇧ ↵）で領域全体に拡大し、もう一度で元に戻します。下にある分割はそのまま保たれます。
• ペインはビューであってセッションではない：ペインを閉じても（Ctrl/⌘ ⇧ \）、ターミナルの表示が消えるだけで、タブとそのシェルはアタッチされたままです。ペイン数は次回起動時に復元されます。

キーボードショートカット#

ブロードキャストと送達確認#

ブロードキャストパネルから、選択した任意のエージェント — プロジェクトやホストをまたいで — に 1つの指示を送信できます。各ターミナルにペーストして回るのと違い、各エージェントが送達確認を返すため、 指示が実際に届いたかどうかが分かります。

• プロジェクト単位、ホスト単位、または個別にエージェントをチェックしてターゲットを指定。
• エージェントごとの配信状況を表示。失敗した配信は目立って表示され、個別に再試行できます。
• 典型的な用途：フリート全体の一時停止、新しい制約の通達（「今後のコミットメッセージはすべて英語で」）、エージェント横断での進捗確認。

ホストの運用#

インストールパネル：新しいホストのプロビジョニング

インストールパネルはまずホストを検査し、実際にサポートできるエージェントCLIとランタイムだけを提示します。 利用できないものは理由付きで示されます。インストールはtmux内で実行されるため、接続が中断されても 中途半端なパッケージツリーが残ることはありません。tmux自体も、なければここからインストールできます。

ホストのテレメトリ

ホストごとのメトリクスは1つのコマンドでまとめて収集されます。

• モード別・コア別のCPU、メモリ、負荷
• ディスクの使用量とスループット、ネットワーク、ファイルディスクリプタ
• NVIDIA GPUがある場合はその使用率

SFTPブラウザとエディタ

ファイルアクセスは同じSSH接続に相乗りします。書き込みはアトミックで、変更チェック付きです。 同じディレクトリで作業中のエージェントがそのファイルを変更していた場合、保存は黙って上書きせずに拒否されます — まず何が変わったかを確認してから判断してください。

オーケストレーターとOllama#

オーケストレーターはローカルモデルで動く運用アシスタントです。目的（たとえば「agent-3の進捗が 止まった原因を調べて」）を与えると、フリートの状態を調べ、過去のコンテキストを取り出し、ツール呼び出しを 1つずつ進めます。自分で有効化するまでは無効のままです。

前提条件

1. Ollamaをインストールし、起動しておきます。
2. チャットモデルと埋め込みモデルを1つずつ取得します。例：

ollama pull qwen3             # チャットモデル（一例 — ハードウェアに合わせて選択）
ollama pull nomic-embed-text  # 埋め込みモデル。セマンティック検索に使用

承認フロー

• ホストを変更する操作はすべて、明示的な承認まで保留されます。承認カードには、ツール、その完全な引数、対象ホスト、モデルが述べた根拠が表示されます。
• 破壊的な操作は、信頼レベルにかかわらず、すべてのホストで確認されます。
• ツールは固定のホワイトリストで、各ツールには宣言時に固定されたリスク階層が付きます。実行は、階層 × ホストの信頼レベル × 実行トリガーを組み合わせた単一のゲートを通過します。
• リモートの出力はデータとしてマークされてモデルに渡され、指示のように見えるテキストには承認カードと意思決定ログでフラグが立ちます（プロンプトインジェクション対策）。
• すべての実行の全ステップが記録されます — 拒否・却下・未回答のまま残った提案も含めて。

定期パトロール

オーケストレーターはスケジュールに沿ってフリートをパトロールし、停滞したエージェントを報告できます。 スケジュール実行では読み取り以外のツールがすべて無条件に拒否され、この制限は設定で変更できません。 パトロールは問題を見つけられますが、対処は常にあなたの判断を待ちます。

スキルとメモリ

• スキル：再利用可能な手順 — 適用条件、手順、使用ツール、制約 — で、同じ条件が再び現れると自動でマッチします。オーケストレーターが提案したスキルはレビューキューに入り、承認されるまで一切効力を持ちません。
• メモリ：プロジェクトの事実、表明された好み、エージェントの活動をインデックス化し、語句でも意味でも検索できます。埋め込みはローカルで計算され、データがマシンの外に出ることはありません。既知のパターンに一致する認証情報は、保存前にマスキングされます。

ライフサイクルの意味論#

これを頭に入れておけば、「今タスクを消してしまった？」と焦る瞬間は二度と訪れません。

ソースからのビルド#

Go 1.25+とNode 20+が必要です。先にフロントエンドをビルドし（バイナリに埋め込まれます）、次にGoをビルドします。

git clone git@github.com:tan-zhuo/AgentMux.git
cd AgentMux
cd frontend && npm install && npm run build && cd ..
go build -o agentmux .
./agentmux

LinuxではWebKitGTKのヘッダとgtk3ビルドタグが必要です。

sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go build -tags gtk3 -o agentmux .

Windowsで、コンソールウィンドウなしのダブルクリック起動できるGUIバイナリを作るには次のとおりです。

go build -ldflags "-H windowsgui" -o agentmux.exe .

より詳しい情報（テスト、リリースの作成）は docs/development.md を参照してください。

トラブルシューティング#

macOSで「壊れている」と表示される／開けない

未署名ビルドに対する通常のゲートであって、ファイルの破損ではありません。 インストールの表に従うか、コマンド1つで解決できます： xattr -dr com.apple.quarantine /Applications/AgentMux.app。

Linuxで起動しない／ライブラリが見つからない

ほぼ確実にWebKitGTKランタイムです。Debian/Ubuntu：sudo apt install libwebkit2gtk-4.1-0、 Fedora：sudo dnf install webkit2gtk4.1。

Windowsでウィンドウがまったく表示されない

GUIビルドにはエラーを表示するコンソールがありません。データディレクトリ （%APPDATA%\AgentMux）のstartup-error.logを確認してください — 実際の失敗理由がそこに書かれています。

接続時に「Host key mismatch」と表示される

ホストのキーが、初回接続時にピン留めされたものと異なっています。まず原因を突き止めてください。 ホストの再インストールやIPの再割り当てなら正常です — ホストのレコードを削除して追加し直してください。 何も変わっていないはずなら、中間者攻撃の可能性として扱い、フィンガープリントを別経路で検証してください。

ステータスバーにキーチェーンが利用できないと表示される

暗号化のマスターキーは通常、OSのキーチェーン（Keychain / 資格情報マネージャー / Secret Service）に 置かれます。キーチェーンが使えない環境（最小構成のLinuxデスクトップでよくあります）では、AgentMuxは パーミッション0600のファイルにフォールバックし、その旨をステータスバーに表示します。 動作には支障ありません。Linuxでキーチェーン保存に戻すには、gnome-keyringなどのSecret Service実装を インストールして有効化してください。

対象ホストにtmuxがない

そのホストのインストールパネルを開いてください — 一覧にtmuxがあり、AgentMuxが適切なパッケージマネージャでインストールします。

オーケストレーター／セマンティック検索が使えない

Ollamaが起動していること（ollama listでモデルが表示されること）、チャットモデルと 埋め込みモデルの両方が取得済みであることを確認してください。Ollamaがない場合、この2機能は無効のままですが、 他の機能には影響しません。

データはどこに保存されますか？

すべての状態は、アプリケーションデータディレクトリ（Windowsでは%APPDATA%\AgentMux）内の SQLiteファイル1つに収まります。このディレクトリをバックアップすればすべてのバックアップになり、 削除すれば完全なリセットになります。認証情報はAES-256-GCMで暗号化して保存され、鍵はOSのキーチェーンにあります。

サポートを受ける#

• GitHubのissueを作成してください — プラットフォーム、バージョン、（あれば）startup-error.logを添えると、解決が大幅に早くなります。
• オーケストレーターの内部（ツールゲート、信頼レベル、メモリとスキルのレイヤー）はオーケストレーター設計ドキュメントに記載されています。
• 作者のブログ：tanzhuo.xyz