AI导哈

终端代理池管理工具

Agent Mux 是一个基于 tmux 的代理池管理工具，通过 tmux 会话和窗口管理多个交互式 CLI 代理，支持创建、切换、关闭项目以及代理的生成、交互和输出读取。

  • by JinchengGao-Infty
  • JavaScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 JinchengGao-Infty/agent-mux

使用说明

我有一个新版本，名为Hydra，功能更强大，详见 https://github.com/JinchengGao-Infty/Hydra?tab=readme-ov文件

Mux探员

Mux探员是 tmux支持的代理池 加上一个小 MCP（模型上下文协议）服务器. 它将“项目”作为tmux会话进行管理，并将每个交互代理生成一个tmux窗口，以便您可以：

  • 创建/列出/切换/关闭项目（tmux会话）
  • 生成/列出/附加/中断/终止代理（tmux窗口）
  • 向代理发送文本（键入+Enter）
  • 读取代理的输出（通过 tmux capture-pane)

此仓库将代理多路复用器实现保持在 lib/agent-mux/，并通过以下方式将其作为MCP工具公开 servers/agent-mux-server.mjs.

为什么选择tmux？

tmux提供了可以手动检查的持久会话，以及捕获渲染终端的简单方法 输出——使其成为编排交互式CLI代理的实用基础。

特性

  • 专用tmux插座：使用 tmux -L ccx ... 因此，它不会干扰您的默认tmux
  • 一个项目=一次会议, 一个代理=一个窗口 （单窗格）
  • 持久注册表 在...之下 .ccx/projects/<project>/agents.json
  • 每个代理日志文件 通过 pipe-pane 到 .ccx/projects/<project>/logs/<agent>.log
  • 保守名称验证 对于项目和代理商

需求

  • Node.js 18+（ESM）
  • tmux 在 PATH
  • 可选代理CLIs（仅在使用默认命令时需要）：
    • claude （默认参数： --dangerously-skip-permissions)
    • codex （默认参数： --yolo)
    • gemini （默认参数： --yolo)

安装

从repo根目录：

npm install

快速启动（手动tmux）

创建项目并生成代理后，您可以检查tmux会话：

tmux -L ccx attach -t <project>
# Detach without closing: Ctrl-b d
# Switch windows: Ctrl-b 0/1/2/...

快速启动（MCP服务器）

运行MCP服务器（stdio）：

node servers/agent-mux-server.mjs

然后在MCP客户端中将其注册为stdio服务器。示例（客户端格式各不相同）：

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

用法示例

通过MCP工具

典型流程：

  1. 创建/选择项目
  • create_project({ "name": "my-project", "cwd": "/path/to/workdir" })
  • switch_project({ "name": "my-project" })
  1. 生成一个代理
  • spawn_agent({ "type": "codex", "name": "codex-1" })
  1. 跟它说话
  • send_to_agent({ "name": "codex-1", "text": "hello" })
  1. 读输出
  • 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 })

代理I/O

  • 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 （string）：用于注册表/日志存储的基本目录；默认 process.cwd()
  • options.tmuxSocketName （string）：tmux套接字名称 tmux -L；默认 ccx
  • options.tmuxBinary （string）：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 （string）：代理工作目录（默认为项目cwd）
    • options.command / options.cmd （string）：覆盖已执行的命令
    • options.args （string[]）：附加到默认值的额外参数（或与自定义命令一起使用）
  • 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 }

代理I/O

  • 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）

MIT许可证

版权所有（c）2026 Agent Mux贡献者

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

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

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

相关 MCP