Agent Mux

🚀 Agent Mux

Agent Muxは、tmuxベースのエージェントプールと小さなMCP (Model Context Protocol)サーバーを備えたシステムです。tmuxセッションとして「プロジェクト」を管理し、各インタラクティブエージェントをtmuxウィンドウとして生成することで、以下の操作が可能です。

• プロジェクト（tmuxセッション）の作成、一覧表示、切り替え、閉じる
• エージェント（tmuxウィンドウ）の生成、一覧表示、アタッチ、中断、終了
• エージェントにテキストを送信（入力 + Enter）
• エージェントからの出力を読み取る（tmux capture-paneを介して）

このリポジトリでは、lib/agent-mux/以下にagent - muxの実装を保持し、servers/agent-mux-server.mjsを介してMCPツールとして公開しています。

⚠️ 重要提示

私は新しいバージョンのHydraを持っています。こちらの方がより強力です。詳細はhttps://github.com/JinchengGao-Infty/Hydra?tab=readme-ov-fileを参照してください。

🚀 クイックスタート

手動tmuxを使用する場合

プロジェクトを作成し、エージェントを生成した後、tmuxセッションを確認することができます。

tmux -L ccx attach -t <project>
# 閉じずにデタッチ: Ctrl-b d
# ウィンドウを切り替える: Ctrl-b 0/1/2/...

MCPサーバーを使用する場合

MCPサーバーを実行します（標準入出力）。

node servers/agent-mux-server.mjs

次に、MCPクライアントでこれを標準入出力サーバーとして登録します。例（クライアントの形式は異なります）：

{
  "mcpServers": {
    "agent-mux": {
      "command": "node",
      "args": ["servers/agent-mux-server.mjs"]
    }
  }
}

✨ 主な機能

• 専用のtmuxソケット：tmux -L ccx ...を使用するため、デフォルトのtmuxと干渉しません。
• 1つのプロジェクト = 1つのセッション、1つのエージェント = 1つのウィンドウ（シングルペイン）
• .ccx/projects/<project>/agents.json以下に永続的なレジストリ
• pipe-paneを介して.ccx/projects/<project>/logs/<agent>.logにエージェントごとのログファイル
• プロジェクトとエージェントの保守的な名前検証

📦 インストール

リポジトリのルートから次のコマンドを実行します。

npm install

💻 使用例

MCPツールを介して

典型的な流れは以下の通りです。

1. プロジェクトを作成/選択する

• create_project({ "name": "my-project", "cwd": "/path/to/workdir" })
• switch_project({ "name": "my-project" })

2. エージェントを生成する

• spawn_agent({ "type": "codex", "name": "codex-1" })

3. エージェントと会話する

• send_to_agent({ "name": "codex-1", "text": "hello" })

4. 出力を読み取る

• read_agent_output({ "name": "codex-1", "lines": 50 })

ライブラリとして（Node.js）

import { AgentMux } from "./lib/agent-mux/index.mjs";

const mux = new AgentMux({ projectRoot: process.cwd(), tmuxSocketName: "ccx" });

mux.create_project("my-project", process.cwd());
mux.spawn_agent("codex", "codex-1");
mux.send_to_agent("codex-1", "hello");

const { output } = mux.read_agent_output("codex-1", 50);
console.log(output);

📚 詳細ドキュメント

MCPツール

MCPサーバーは以下のツールを公開しています（名前はAgentMuxのメソッドと一致します）。

プロジェクト管理

• create_project({ name, cwd? })
• list_projects({})
• switch_project({ name })
• close_project({ name })

エージェント管理

• spawn_agent({ type, name, options? })
• list_agents({ project? })
• attach_agent({ name })
• interrupt_agent({ name })
• kill_agent({ name })

エージェントの入出力

• send_to_agent({ name, text })
• read_agent_output({ name, lines? })
• send_to_window({ window, text })

API（ライブラリ）

命名規則

プロジェクト名とエージェント名は以下の正規表現に一致する必要があります。

• ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$

new AgentMux(options?)

• options.projectRoot (文字列): レジストリ/ログの保存に使用されるベースディレクトリ; デフォルトはprocess.cwd()
• options.tmuxSocketName (文字列): tmux -Lのためのtmuxソケット名; デフォルトはccx
• options.tmuxBinary (文字列): tmuxバイナリ; デフォルトはtmux

プロジェクト管理

• create_project(name, cwd?) → { project, cwd, created, storageDir }
• list_projects() → Array<{ project, cwd, sessionExists, hasRegistry, current }>
• switch_project(name) → { project, switched, clients }
• close_project(name) → { project, killed, clearedCurrent }

エージェント管理

• spawn_agent(type, name, options?) → エージェントエントリ（tmuxウィンドウ + レジストリ + ログパス）
  • type: claude / codex / geminiのいずれか
  • options.cwd (文字列): エージェントの作業ディレクトリ（デフォルトはプロジェクトの作業ディレクトリ）
  • options.command / options.cmd (文字列): 実行するコマンドを上書き
  • options.args (文字列配列): デフォルトに追加する追加引数（またはカスタムコマンドとともに使用）
• list_agents(project?) → { project, agents: [...entries with alive:boolean] }
• attach_agent(name) → { project, agent, attached, clients }
• interrupt_agent(name) → { project, agent, interrupted } （Ctrl+Cを送信）
• kill_agent(name) → { project, agent, killed }

エージェントの入出力

• send_to_agent(name, text) → { project, agent, sent, bytes }
• send_to_window(window, text) → { project, window, sent, bytes }
• read_agent_output(name, lines=200) → { project, agent, lines, output }

🔧 技術詳細

デフォルトでは、Agent MuxはprojectRoot/.ccx/projects/以下に状態を保存します。

.ccx/projects/<project>/
  project.json
  agents.json
  logs/<agent>.log
.ccx/projects/current.json

.ccx/に書き込み権限がない場合は、${os.tmpdir()}/ccx-agent-mux/projects/にフォールバックします。

📄 ライセンス

MITライセンス

Copyright (c) 2026 Agent Mux Contributors

このソフトウェアおよび関連ドキュメントファイル（「ソフトウェア」）のコピーを取得するすべての人に対して、無料で、ソフトウェアを制限なく取り扱うことができる許可がここに与えられます。これには、使用、コピー、変更、マージ、公開、配布、サブライセンス、および/またはソフトウェアのコピーを販売する権利が含まれ、ソフトウェアが提供される人に対しても同じことを許可することができますが、以下の条件に従う必要があります。

上記の著作権表示およびこの許可表示は、ソフトウェアのすべてのコピーまたは実質的な部分に含まれる必要があります。

ソフトウェアは「現状のまま」提供され、明示的または黙示的ないかなる保証もなく、商品性、特定の目的への適合性、および非侵害の保証を含みますが、これらに限定されません。いかなる場合も、著者または著作権者は、契約、不法行為、またはその他の方法による訴訟において、ソフトウェアまたはソフトウェアの使用またはその他の取り扱いに関連するいかなる請求、損害、またはその他の責任についても責任を負いません。