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 贡献者

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人，允许其不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向其提供软件的人这样做，但需遵守以下条件：

上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。

软件按“原样”提供，不附带任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对因合同、侵权或其他方式引起的任何索赔、损害或其他责任负责，无论是在与软件或软件的使用或其他交易有关的任何行动中。