Agent Mux

🚀 Agent Mux

Agent Mux 是一個基於 tmux 的代理池，外加一個小型MCP（模型上下文協議）服務器。它將“項目”作為 tmux 會話進行管理，並將每個交互式代理作為 tmux 窗口生成，讓你能夠：

• 創建、列出、切換、關閉項目（tmux 會話）
• 生成、列出、附加、中斷、終止代理（tmux 窗口）
• 向代理發送文本（輸入內容並回車）
• 從代理讀取輸出（通過 tmux capture-pane）

此倉庫將 agent-mux 實現存於 lib/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。
• 一個項目 = 一個會話，一個代理 = 一個窗口（單窗格）。
• 持久註冊表：位於 .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/。

🔧 技術細節

tmux 提供了可手動檢查的持久會話，以及一種捕獲渲染終端輸出的簡單方法，這使其成為編排交互式 CLI 代理的實用基礎。

📄 許可證

本項目採用 MIT 許可證。

版權所有 (c) 2026 Agent Mux 貢獻者

特此免費授予任何獲得本軟件及相關文檔文件（“軟件”）副本的人，允許其不受限制地處理本軟件，包括但不限於使用、複製、修改、合併、發佈、分發、再許可和/或出售軟件副本的權利，並允許向其提供軟件的人這樣做，但需遵守以下條件：

上述版權聲明和本許可聲明應包含在所有副本或軟件的重要部分中。

軟件按“原樣”提供，不附帶任何形式的明示或暗示保證，包括但不限於適銷性、特定用途適用性和不侵權的保證。在任何情況下，作者或版權持有人均不對因合同、侵權或其他方式引起的任何索賠、損害或其他責任負責，無論是在與軟件或軟件的使用或其他交易有關的任何行動中。