ドキュメント

AgentMuxとは#

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

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

動作要件#

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

管理対象ホスト

• リモートホスト（Linux / macOSなどUnix系）：POSIXシェル、tmux、SSHアカウント。tmuxがなくても問題ありません — インストールパネルから導入できます。
• リモートWindowsホスト：OpenSSH Serverを有効にするだけです。tmuxのない環境のため、セッションはAgentMux内蔵のセッションデーモンが担います — 初回利用時にSFTPで自動配備され、プロトコルはSSHポートフォワード上を流れ、リモートシェルは一切経由しません。
• 画面専用ホスト：操作せず見ておきたいだけのマシンなら、RDPまたはVNCが応答するアドレスが1つあれば十分です — SSHは不要で、資格情報を事前に保存することもありません（ホストの運用 → 画面専用ホストを参照）。
• 手元の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

サーバー版（ヘッドレス）

同じアプリケーションには完全に静的なヘッドレスビルドもあります： agentmux-server-linux-amd64.tar.gz と agentmux-server-linux-arm64.tar.gz。 GTKもWebViewもリンクせず、ディスプレイも不要 — 任意のLinuxサーバーで実行すれば、 完全なWebアプリケーションを提供します。導入にはワンラインのインストールスクリプト （systemdサービスの登録と自動更新も面倒を見ます）を推奨します。 ヘッドレスサーバーの節を参照してください。

Android

1. agentmux-android.apk（Android 8.0+ · arm64）をダウンロードし、スマホまたはタブレットにインストールします — 「提供元不明のアプリ」の許可が必要です。
2. 初回起動時にフォアグラウンドサービスが内蔵コアを起動し、WebViewが 127.0.0.1 に接続します。サーバーは一切不要です。
3. リポジトリに署名鍵が設定されている場合は正式署名のAPKになり上書き更新できます。未設定の場合はdebug署名 — インストールはできますが、署名を切り替える前に旧版のアンインストールが必要です。

クイックスタート#

最初の管理対象エージェントまで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自体も、なければここからインストールできます。

ワンクリックインストールの対象は、エージェントCLI（Claude Code、Codex、Gemini CLI、Grok CLI、OpenCode、 Aider、Cursor CLI）と、Node、Python、tmux、Docker、Ollamaなどのランタイムです。Dockerは6通りの方法 （公式スクリプトを最優先、次に各ディストリビューションのパッケージ、macOSはHomebrew経由のDocker Desktop）を用意し、 ネットワークが必要とする場合はミラーで再試行します。エンジンのインストール後はデーモンを起動し、 ユーザーをdockerグループに追加したうえで、グループの反映には再ログインが必要であることを明示します。

ホストのテレメトリ

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

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

SFTPブラウザとエディタ

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

リモートデスクトップ（内蔵RDP / VNCビューア）

画面そのものが必要な作業もあります。ウィンドウを要求するインストーラ、GUIテスト、人が見ておくべきマシン。 ホストを右クリックしてデスクトップを開くと、よく使われる3つのポート — 3389（RDP）と 5900 / 5901（VNC）— が同時に試されます。それ以上は意図的に試しません：他人のマシンを勝手に ポートスキャンするツールはまともなツールではないからです。SSHホストでは、この接続は そのホストが既に張っているSSH接続を通ります。ループバックだけを待ち受けるデスクトップでも、 ネットワークに何も開ける必要はなく、2つ目の資格情報も要りません。

• ビューアはアプリの中にあります：デスクトップの画面はターミナル領域のタブとして開き、ターミナルペインと並べられます。画面のスクリーンショットではなく本物のプロトコルクライアントです — VNCはnoVNC、RDPはWebAssemblyにコンパイルされたIronRDP — で、必要になったときだけ読み込まれるため、デスクトップを開かない人は1バイトも支払いません。リモートの解像度はペインのサイズに追従します。
• ビューアがアプリの中にあるということは、この機能があらゆるクライアントで使えるということです — デスクトップアプリ、ブラウザ、タブレット、スマホ。手元に何がインストールされているかには、もう依存しません。
• ログインの資格情報はセッションを開くときに入力し、既存の経路でホストに送られ、どこにも保存されません。
• Windowsがログインを拒否したときは、NTステータスコードではなく、実際に何が拒否されたのかが表示されます：アカウントのロックアウト（あと何分で解除されるかも）、パスワードの期限切れ、アカウントの無効化、Remote Desktop Usersグループに未所属、ログオン時間の制限、ドメインプレフィックスの欠落 — よくある原因はそれぞれ対処法付きで翻訳されます。
• デスクトップアプリには引き続き「システムクライアント」の選択肢もあります：応答したポートをこのPCのループバックへSSH転送し、手元のビューア — Windowsのmstsc、macOSの「画面共有」、LinuxのRemminaやFreeRDP — に渡します。最後のクライアントが離れて5分後に転送は自動的に閉じ、SSHのリースが解放されます。ビューアが1つも入っていない場合、転送は開いたままアドレスが報告されます。
• どのデスクトップを提供するかはホストごとに記憶されます — 記憶されるのは実際に応答したエンドポイントだけで、掛け間違えたポートは決して残りません — ので、2回目以降は尋ねません。この記憶はこのインストールではなくホストに属するため、設定のエクスポートにも同行します。

画面専用ホスト

マシンを見たいことと、マシンで作業したいことは別の欲求です。ホスト追加時に 「リモートデスクトップ」の種類を選ぶのが前者です：必要なのは名前、アドレス、OSだけ — OSがプロトコルを決め（WindowsはRDP、macOS / LinuxはVNC）、ポートを提案します。どちらも変更できます。 資格情報の欄はそもそもありません：デスクトップが要求するものはセッションを開くときに入力し、 どこにも保存されません。

• ツリー上では、それは正確に「画面」です：ターミナルなし、エージェントなし、ワークスペースなし、ジャンプホストの候補にもならず、SSH接続プールの席も持ちません — シェルを必要とする場所は、これをシェルとして提示しません。
• 接続はデスクトップポートへの直接ダイヤルです。ごく普通のリモートデスクトップクライアントと同じです。「接続テスト」はそのポートをダイヤルし、レイテンシを報告します。
• 作業できるマシンへの昇格：詳細パネルはついでにポート22を調べます。SSHが応答すれば「SSHホストとして追加」ボタンが現れ、アドレスが記入済みのホストダイアログが開きます — 完全なホストが新規に作られ、画面専用の行はそのまま残ります。SSHが応答せず、OSがWindowsの場合は、OpenSSH Serverを有効にするPowerShellコマンドがワンクリックコピー付きでそのまま提示されます — すでに開いているデスクトップペインに貼り付けて実行し、戻って更新ボタンを押してください。
• OpenSSHを有効にしたら、そのマシンを「リモートWindows」ホストとして追加します。エージェントはネイティブに動きます — PowerShell、MSVC、WPF — そしてAgentMuxのセッションデーモンが生かし続けるので、ウィンドウを閉じても何も止まりません。以降、そのマシンは画面でもあり、作業場所でもあります。

ホストのハードウェア構成

メトリクスパネルは「このマシンが何をしているか」だけでなく「このマシンが何であるか」にも答えます： CPUのモデル名、メモリモジュールの仕様、物理ドライブ、グラフィックスアダプタ。 これらは静的な情報なので、3秒ごとのポーリングではなく、セッション内でキャッシュされる一度きりの読み取りで取得されます。

ヘッドレスサーバー#

AgentMuxのコアはウィンドウなしでも動きます：GTKもWebViewもリンクしない完全に静的なヘッドレスビルドが、 任意のLinuxサーバーから完全なWebアプリケーションを提供します — ターミナル、エージェント、ブロードキャスト、 ファイル閲覧、リモートデスクトップ。デスクトップ版と同じ機能一式であって、縮小版ではありません。 デスクトップアプリ、スマホ、タブレット、あらゆるブラウザがそこに接続でき、 同じホスト構成と、同じ実行中のセッション群が見えます。

ワンラインインストール（推奨）

curl -fsSL https://raw.githubusercontent.com/tan-zhuo/AgentMux/main/scripts/install-server.sh | bash

スクリプトはLinuxサーバー（amd64 / arm64）上で必要なことをすべて、呼び出したユーザーの権限のまま行います — rootは不要です：

• 現在のアーキテクチャ用のサーバー版をダウンロードして.sha256を検証し、~/.local/binにインストールします — 新しいファイルを書いてからアトミックにリネームするため、中途半端なバイナリは決して存在しません。
• systemdのユーザーサービス（~/.config/systemd/user/agentmux.service、失敗時は自動再起動）を登録し、lingerを有効にします — SSHを切断しても、ログアウトしても、サービスは動き続けます。systemdのないマシンでは、nohupと@rebootのcrontabにフォールバックします。
• 既定でHTTPSを有効化し（自己署名証明書）、:8642を待ち受けます。
• 起動後、サーバーが実際に応答することを確かめてから成功を報告します。起動しなかった場合はサービスログの該当行がそのまま表示され、最も多い原因（ポートの競合 — --addrで別のポートを）が提示されます。
• 成功すると、クライアントに必要な3つ — アドレス、アクセストークン、証明書フィンガープリント — が表示されます。

主なオプション（パイプで実行する場合はbash -s --の後に指定します）：

手動で実行する

# サーバー版（agentmux-server-linux-*）：実行すること＝サービス提供。既定は :8642、平文HTTP
./agentmux

# フラグ付き：全インターフェースで待ち受け、自己署名HTTPS
./agentmux --addr 0.0.0.0:8642 --tls

# デスクトップ版のバイナリも同じモードに入る
agentmux --serve --addr 0.0.0.0:8642 --tls

初回起動時のログにはアクセストークン（48桁の16進数。データディレクトリのserve-tokenにパーミッション0600で保存）と、 TLS有効時には証明書のSHA-256フィンガープリントが出力されます — すべてのクライアントがペアリング時に照合するのはこの行です。

暗号化と信頼：自己署名証明書のフィンガープリントピン留め

自己署名証明書を保証してくれるCAはいないので、誰を信じるかは各デバイスが決めます：クライアントは初回接続時に 証明書を取得してSHA-256フィンガープリントを表示し、あなたがサーバーのログの行と見比べてから承認します。 以降そのデバイスはその証明書だけを受け入れます — 名前も有効期限も見ません。フィンガープリントが変われば接続は拒否されます。 アドレスを正規のCA証明書に切り替えると、ピン留めは自動的に退役し、通常の検証に戻ります。 持ち運ぶべき値 — トークン、アドレス、フィンガープリント — にはすべてワンクリックコピーが付いています： それらはクリップボードのためのものであって、目で書き写すためのものではありません。

制限：サーバー版が公開されているのはLinux（amd64 / arm64）のみです。macOSやWindowsから提供したい場合は、 デスクトップアプリのサーバーモードを使うか、 go build -tags headlessで自分でビルドしてください。

コア切り替えとサーバーモード#

すべてのAgentMuxウィンドウの背後には「コア」があります — ホスト構成、SSH接続、鍵、すべての状態を 保持する部分です。ウィンドウは既定でこのデバイスのコアを見ていますが、両者は切り離せます： ウィンドウは別のマシンのコアを見に行けますし、このデバイスのコアを別のデバイスに 見せることもできます。この2方向が、設定の中で隣り合う2つのページです。

ウィンドウをリモートのコアに向ける（設定 → 接続モード）

1. 「リモートサーバー」を選び、serveインスタンスのアドレスを入力します。例：https://192.168.1.10:8642。
2. 相手が自己署名HTTPSの場合はフィンガープリントカードが表示されます：サーバーのログ（または相手側の「サーバーモード」ページ）と見比べて、「一致を確認して信頼し、接続」で承認します。
3. そのマシンのアクセストークンを一度入力すると、ウィンドウが切り替わります。

切り替え後のウィンドウは、そのマシンの1枚のスクリーンです：ホスト構成、SSH鍵、接続、すべての状態は リモート側にあり、このデバイスが覚えるのはアドレスとフィンガープリントだけです。「このデバイス」に戻せば 再びローカルのデータが見えます — 両者は独立していて、同期されることはありません。

• 推奨の形：自宅のデスクトップ機やLAN内のサーバー1台がコアを動かし（ヘッドレス版またはサーバーモード）、ノートPC・スマホ・タブレットはすべてそこを向きます — SSH鍵とジャンプホストの設定はその1台に1回だけ。どのデバイスからも、同じホスト群と同じ実行中のターミナルが見えます。
• 必ず帰り道があります：リモート側に届かないときも真っ白なウィンドウにはなりません — 何が失敗したかを説明するエラーページが表示され、「再試行」と「このデバイスのコアに戻る」の2つのボタンがあります。
• Androidアプリにも同じ「設定 → 接続モード」があります：既定は端末に内蔵されたコアで、リモートインスタンスに向けることもできます。

このPCをサーバーにする（設定 → サーバーモード）

逆方向：デスクトップアプリ自身が、何も追加インストールせずに、他のデバイスからの接続を受け付けられます。

1. 設定 → サーバーモードで待ち受けアドレスを確認します — 既定の:8642は全インターフェース、127.0.0.1:8642はこのマシンのみです。
2. 「暗号化（HTTPS、自己署名証明書）」は既定でオンです。「有効化」を押します。
3. ページに接続アドレス、アクセストークン、証明書フィンガープリントがワンクリックコピー付きで表示されます — スマホアプリの「設定 → 接続モード」にアドレスを入れ、トークンを貼り、フィンガープリントを見比べてください。

ウィンドウとWebは1つのコアの2つの顔です：スマホに見えているのは、まさにあなたのデスクトップ上の ホストとターミナルで、操作は双方向にリアルタイムで通じます。スイッチの状態は記憶され、次回起動時に復元されます。

タブレットとスマホ#

最近のブラウザなら、完全なアプリケーションがそのまま開きます — Androidタブレット、iPad、スマホ。 ターミナル、エージェント、ツールキット、ファイル閲覧、リモートデスクトップのすべてが使え、 読み取り専用のビューではありません。

接続先のサーバーを用意する

ヘッドレスサーバーの節のとおりに1台立てるか （Linuxマシンに1行）、デスクトップアプリの サーバーモードをオンにします。 どちらの道でも、同じ3つが手に入ります：アドレス、アクセストークン、証明書フィンガープリント。

タブレットで開く

1. ブラウザで https://ホスト:8642 を開きます（自己署名証明書の場合、ブラウザの警告ページで一度だけ続行を選びます。平文HTTPで立てた場合は http:// です）。
2. トークンを一度入力すれば、以降はブラウザが保持します。
3. iPadはSafariの「共有 → ホーム画面に追加」、AndroidはChromeの「ホーム画面に追加」。以降はアドレスバーのない単体アプリとして動きます。

ブラウザを閉じても何も止まりません — デスクトップの窓を閉じるのと同じで、エージェントはリモートのtmuxの中で生きています。

Androidネイティブアプリ

各リリースには agentmux-android.apk（Android 8.0+ · arm64）が付属します。これは上の方法より一歩進んでいて、 サーバー版と同一のコアを内蔵し、端末上でフォアグラウンドサービスとして起動、WebViewが 127.0.0.1 に接続します。 SSHはスマホやタブレットから直接発行され、設定と鍵は端末内に残ります — 常時起動のマシンは一台も要りません。

• フォアグラウンドサービスは意図的です：これがないと画面ロック後にAndroidがプロセスを凍結し、すべてのSSH接続が切れます。そのため通知領域に常駐通知が表示されます。
• エージェント自体はリモートのtmuxの中で生きているため、アプリがシステムに終了させられても影響はありません — 開き直せば再接続します。
• リモートモード：アプリの「設定 → 接続モード」から、内蔵コアの代わりにserveインスタンスを指定できます。相手が自己署名HTTPSの場合、アプリは証明書を取得してフィンガープリントカードを表示します — サーバーのログと見比べて承認すれば、以降この端末はその証明書だけを受け入れます。
• 既知の制限：自己署名＋フィンガープリントピン留めのサーバーに対しては、リモートデスクトップビューアが使えません（AndroidのWebViewはWebSocketの証明書エラーをアプリに裁かせてくれません）。ターミナルほか他の機能には影響なし。正規のCA証明書に替えれば制限は解けます。

親指のために作り直したレイアウト

• 幅768px未満では、左右のパネルがオーバーレイのドロワーになります。開くのは一度に1つで、タブを選ぶと閉じます。
• ステータスバーの位置は下部ナビゲーションバーに譲ります：ツリー、コマンドパレット、詳細パネル、設定の4つを親指の高さのボタンとして並べ、セーフエリアにも対応します。
• ダイアログとコマンドパレットは、余白のない画面ではデスクトップのマージンに固執しません。

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

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

前提条件

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

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

承認フロー

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

定期パトロール

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

スキルとメモリ

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

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

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

人の対応を待っているエージェント

質問しているエージェント、結果を確認してほしいエージェント、タスクがなくプロンプトで待機しているエージェント — 以前はツリー上でどれも「running」でした。現在はポーリングが各ペインを読んで分類し、 人が見る必要のある変化に持続的なマークを立て、誰かが実際に見た時点（ターミナルを開く、返答する、 あるいは手動で消す）でマークを下ろします。

• マークはツリーの行に付き、折りたたまれたワークスペースやプロジェクトにも波及します。展開しなくても、どこで自分が必要とされているか分かります。
• ターミナルのタブと詳細パネルにも同じマークが出ます。

切断からの自動再接続

回線を失ったターミナルは終わりではありません。向こう側のtmuxセッションは動き続け、中のエージェントも作業を続けており、 壊れたのはパイプだけです。そこでパイプは張り直されます — 同じshell id、同じスクロールバック、同じペイン。 待機は1秒から15秒へ伸び、約5分で自動再試行をあきらめます。その時点でも従来の手動再アタッチのボタンは残っています。

• 自分の意思で終了したセッションはそのままにします。終了コードは決定であって、障害ではありません。
• keepaliveは2種類。それぞれ別の問いに答えます。TCP keepaliveは途中の機器にアイドル接続を忘れさせないため、SSHのkeepaliveは相手がまだ応答することを確かめるためで、pingに10秒返らなければ失敗と見なします。
• 一度きりのコマンド端末は対象外です。掛け直すことはコマンドを再実行することを意味し、Wi-Fiが瞬断しただけでインストールをやり直すのは誰も望まない副作用だからです。

更新と移行#

更新の確認とワンクリック更新

アプリは起動直後、そしてその後6時間ごとにリリースを確認します。新しいバージョンがあると、 タイトルバーの下に1行のバナーが出ます：更新して再起動、リリースノート、あとで。

• 更新はプラットフォームに対応するアセットを進捗バー付きでダウンロードし、公開された sha256 を検証してから実行中のファイルを置き換え（macOSはバンドルごと、Windowsは実行中のプログラムを削除できないため改名して退避）、再起動し、次回起動時に残骸を掃除します。
• 置き換えに失敗した場合は、動作していたビルドへロールバックします。
• 開発ビルドは決して上書きされません — gitで更新するものであり、設定から確認するとその旨が表示されます。

インストールを別のマシンへ持ち運ぶ

設定から構成一式を1つのファイルに書き出せます：ホスト、フォルダ、プロジェクト、ワークスペース、 エージェント定義、必要ならスキルライブラリと環境設定も。そして別のマシンでそれを開きます。

• 暗号化。このマシンのマスターキーではなくパスフレーズで封をします。マスターキーはこのPCのキーチェーンにあり持ち出せないため、データベースをそのままコピーしても向こうでは読めません。Argon2idがパスフレーズを鍵に変え、AES-256-GCMが中身を封じます。コストパラメータは使用のために平文で同行せざるを得ないので、隠すのではなく認証されます — 安価な値に書き換えられたヘッダはファイルを弱くするのではなく、開けなくします。
• SSHパスワードと鍵のパスフレーズは、求めたときだけ同行し、封をするあいだだけ平文で存在し、到着後は新しいマシン自身のマスターキーで封じ直されます。
• インポートは決して上書きしません。同じアドレスのホスト、同じ名前のプロジェクト、同じマシンの同じパス — いずれもそのまま残り、ファイル内でそれを指していたものは、こちらに既にあるほうを指すようになります。同じファイルを二度取り込んでも何も増えず、試しに取り込むこと自体に代償はありません。持ち越せなかったものは明示されます — このマシンにない鍵ファイル、同行できなかった踏み台、こちらで既に使われているセッション名。
• 2つは意図的に置いていきます。ターミナルのレイアウトとエージェントの実行時状態は、構成ではなく「このインストール」を表すものです。オーケストレーターに実行を許すかどうかは各マシンで決めることであり、よそから届いたファイルはその決定ではありません。

ソースからのビルド#

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のキーチェーンにあります。

タブレットから ホスト:8642 に繋がらない

• スキームを確認してください：インストールスクリプトは既定でTLSを有効にするため、アドレスは https:// です。--tls なしで手動起動した場合のみ http:// になります。自己署名証明書はブラウザの警告ページで一度だけ確認を求めます。
• 待ち受けアドレスが 127.0.0.1 にバインドされていないか確認してください — それではネットワークから届きません（既定の :8642 は全インターフェースを待ち受けます）。
• サーバーのファイアウォールで8642が開いているか確認してください（クラウドではセキュリティグループも）。
• タブレットが同じネットワーク、または同じVPNに繋がっているか確認してください。

リモートのコアに切り替えたらエラーページばかり出る

そのエラーページ自体が設計の一部です：serveインスタンスが落ちている、VPNが繋がっていない、 アドレスの打ち間違い — いずれもそこに着地し、何が失敗したかが書かれています。「再試行」を押すか、 「このデバイスのコアに戻る」で戻ってから、サーバー側で systemctl --user status agentmux を 確認してください。切り替えには必ず帰り道があります — リモートモードに閉じ込められることはありません。

serveモードのアクセストークンを忘れた

トークンはデータディレクトリの serve-token に保存され、初回起動時にログにも出力されています。 変更したい場合は、そのファイルを削除して再起動するか、起動時に環境変数 AGENTMUX_TOKEN を指定してください。

Androidアプリがインストール／更新できない

まず「提供元不明のアプリ」を許可してください。署名の競合が出る場合、入っているのはdebug署名のビルド （署名鍵が未設定のときにリポジトリが生成するもの）です — 旧版をアンインストールしてから新版を入れてください。 エージェントはリモートのtmuxの中にいるので影響はありません。

サポートを受ける#

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