tmux-克劳德-mcp服务器

Name: tmux-克劳德-mcp服务器
Author: michael-abdo

作者：michael-abdo8 星标更新：2025-07-05

安装使用来源：spider==github.com

项目介绍

tmux-claude MCP Server

一个高效的模型上下文协议（MCP）服务器，通过 tmux 实现 Claude 实例的分层编排。采用桥接模式架构，与传统的多服务器方法相比，内存使用减少85%。

📸 屏幕截图

演示 1 - 分层实例管理 显示执行者、管理者和专家实例协同工作的分层编排

演示 2 - 实时监控仪表板 基于网络的监控仪表板，展示活跃实例和系统指标

🤖 对于 Claude 代码实例

新加入此仓库？ 如果您是 Claude 代码实例，请从**Claude 快速入门指南**开始，快速了解并获取实用示例。

概览

架构创新

由于 MCP 文档中提到的 1:1 标准 I/O 架构，多个 Claude 实例无法直接访问 MCP 工具。我们的桥接模式解决方案：

单个共享 MCP 服务器进程（总计 50-70MB）
轻量级桥接，通过 Bash 访问多实例
相比启动独立服务器，内存减少 85%
中央状态管理，无竞态条件

核心 MCP 工具

spawn: 创建具有角色的新 Claude 实例（执行者/管理者/专家）
send: 向实例发送文本/提示
read: 读取实例输出
list: 列出活跃实例，并可进行过滤
terminate: 停止实例及其子实例（可选）

新特性

VM 集成: 完整的云 VM 管理，适用于开发环境
计划继续: 在指定时间向所有 tmux 会话发送“Plz continue”消息
工作区模式: 支持隔离（默认）和共享工作区模式
Git 集成: 自动分支管理，适用于共享工作区
冲突检测: 主动识别合并冲突
MCP Git 工具: 5 个新的 Git 操作工具（git_status, git_branch 等）
AI 冲突解决: 使用 Claude 进行智能合并冲突解决
性能优化: 并行启动、消息批处理、缓存
监控仪表板: 实时网络监控仪表板

项目结构

tmux-claude-mcp-server/
├── README.md              # 项目概述和用法
├── LICENSE                # MIT 许可证
├── package.json           # Node.js 依赖项
├── package-lock.json      # 锁定依赖项
├── .gitignore            # 版本控制忽略模式
├── src/                   # 核心源代码
│   ├── simple_mcp_server.js    # 主 MCP 服务器
│   ├── instance_manager.js     # 实例生命周期管理
│   ├── mcp_tools.js            # MCP 工具实现
│   ├── tmux_interface.js       # tmux 集成层
│   ├── reliable_tmux_sender.js # 高可靠性消息传递
│   ├── orchestration/          # 编排组件
│   ├── dashboard/              # 网络监控仪表板
│   ├── role_templates/         # 标准化角色模板
│   └── workflow/               # 工作流编排系统
│       ├── actions/            # 模块化操作实现
│       ├── workflow_engine.cjs # 主工作流引擎
│       └── run_workflow.cjs    # 工作流运行器 CLI
├── scripts/               # 实用脚本
│   ├── mcp_bridge.js           # 多实例 MCP 访问的桥接
│   ├── scheduled_continue.js   # 调度“Plz continue”消息
│   ├── check/                  # 会话检查工具
│   ├── restart/                # 会话重启工具
│   ├── utils/                  # 共享工具
│   │   └── time_parser.js     # 时间解析，用于调度
│   └── api/                    # 监控 API 脚本
├── docs/                  # 文档
│   ├── CHANGELOG.md             # 版本历史
│   ├── CONTRIBUTING.md          # 贡献指南
│   ├── WORKFLOW_GUIDE.md        # 工作流系统指南
│   ├── CLAUDE_GETTING_STARTED.md    # Claude 实例快速入门
│   ├── DOCUMENTATION_INDEX.md       # 文档索引
│   ├── scheduled_continue/          # 计划继续功能文档
│   │   ├── CLI_INTERFACE_DESIGN.md
│   │   ├── TIME_FORMAT_SPECIFICATION.md
│   │   └── SCHEDULING_MECHANISM_ANALYSIS.md
│   ├── analysis/          # 技术分析及发现
│   ├── archive/           # 历史文档
│   └── guides/            # 用户指南和规范
├── tests/                 # 测试套件
│   ├── test_workflow_standalone.cjs  # 独立工作流测试
│   ├── unit/             # 单元测试
│   ├── integration/      # 集成测试
│   ├── e2e/              # 端到端测试
│   └── performance/      # 性能基准测试
├── workflows/             # 工作流系统
│   ├── README.md              # 工作流文档
│   ├── CURRENT_STATUS.md      # 当前状态和使用情况
│   ├── library/               # 可重用的工作流组件
│   ├── examples/              # 示例工作流
│   ├── tests/                 # 工作流测试文件
│   ├── scripts/               # 工作流工具
│   ├── state/                 # 工作流状态存储
│   └── user/                  # 用户创建的工作流
├── state/                # 默认状态目录
├── config/               # 配置文件
├── logs/                 # 日志目录
└── vm-integration/       # 云 VM 管理
    ├── README.md              # VM 集成文档
    ├── vm_manager.js          # 核心 VM 管理类
    ├── vm_cli.js              # 命令行接口
    ├── vm_mcp_tools.js        # MCP 工具集成
    ├── integrate_vm_mcp.js    # MCP 服务器集成
    ├── setup-scripts/         # VM 初始化脚本
    │   └── claude-dev-setup.sh
    └── tests/                 # VM 集成测试
        └── test_vm_integration.js

架构

外部状态存储: 第一阶段使用基于 JSON 文件的注册表，第二阶段及以后准备使用 Redis
项目隔离: 每个 Claude 实例使用 --project 标志进行对话隔离
基于角色的访问: 专家没有访问 MCP 工具的权限，只有执行者/管理者可以进行编排
分层命名: exec_1, mgr_1_1, spec_1_1_1 以明确父子关系
几乎免费的恢复: 使用 --continue 标志重新启动实例

代码收割

此实现收割并适应了现有 tmux-manager 代码库的约 20-30%：

收割的组件

tmux_interface.py → src/tmux_interface.js - 核心 tmux 操作
instance.py → src/instance_manager.js - 实例生命周期管理
manager.py → src/instance_manager.js - 注册和协调
session_manager.py → src/instance_manager.js - 会话操作

被丢弃的组件（60-70%）

所有 CLI 接口
模式匹配/监控系统
事件总线架构
配置管理
布局系统

安装

cd tmux-claude-mcp-server
npm install

配置（必需）

关键点： 您必须为所有 Claude 实例全局配置 MCP 服务器：

claude mcp add tmux-claude -s user node /path/to/tmux-claude-mcp-server/src/simple_mcp_server.js

重要注意事项：

-s user 标志对于分层编排工作是必需的
这使得 MCP 服务器对所有 Claude 实例可用
如果不这样做，生成的实例将无法访问 MCP 工具
详情请参阅MCP 配置指南

验证配置：

claude mcp list
# 应该显示：tmux-claude: node /path/to/simple_mcp_server.js

使用

在正确配置后，MCP 服务器会在 Claude 启动时自动运行。

工具示例

创建执行者

{
  "name": "spawn",
  "arguments": {
    "role": "executive",
    "workDir": "/jobs/auth_system",
    "context": "# 执行者: 认证系统\\n\\n您负责协调 JWT 认证系统的实施..."
  }
}

执行者创建管理者

{
  "name": "spawn", 
  "arguments": {
    "role": "manager",
    以下内容省略，同原文一致。
}

管理者创建专家

{
  "name": "spawn",
  "arguments": {
    "role": "specialist", 
    "workDir": "/jobs/auth_system",
    "context": "# 专家: 用户模型\\n\\n使用 Mongoose 实现用户模型...",
    "parentId": "mgr_1_1"
  }
}

向专家发送任务

{
  "name": "send",
  "arguments": {
    "instanceId": "spec_1_1_1",
    "text": "请实现带有电子邮件、密码和时间戳字段的用户模型"
  }
}

读取专家输出

{
  "name": "read",
  "arguments": {
    "instanceId": "spec_1_1_1",
    "lines": 50
  }
}

列出所有活跃实例

{
  "name": "list",
  "arguments": {}
}

列出管理者的专家

{
  "name": "list",
  "arguments": {
    "parentId": "mgr_1_1"
  }
}

终止已完成的专家

{
  "name": "terminate",
  "arguments": {
    "instanceId": "spec_1_1_1"
  }
}

状态管理

外部状态存储（第一阶段）

位于 ./state/instances.json：

{
  "instances": {
    "exec_1": {
      "instanceId": "exec_1",
      "role": "executive",
      "parentId": null,
      "sessionName": "claude_exec_1",
      "projectDir": "/jobs/auth_system/exec_1",
      "paneTarget": "claude_exec_1:0.0",
      "status": "active",
      "created": "2024-01-01T10:00:00Z",
      "children": ["mgr_1_1"]
    }
  }
}

实例目录结构

/jobs/auth_system/
├── exec_1/
│   ├── CLAUDE.md              # 执行者上下文
│   └── 项目文件...
├── mgr_1_1/  
│   ├── CLAUDE.md              # 管理者上下文
│   └── 项目文件...
└── spec_1_1_1/
    ├── CLAUDE.md              # 专家上下文
    └── 实现文件...

错误恢复

服务器通过使用 Claude 的 --continue 标志实现了几乎免费的恢复：

{
  "name": "restart",
  "arguments": {
    "instanceId": "spec_1_1_1"
  }
}

这将：

检查实例是否实际死亡
在相同的项目目录中重新创建 tmux 会话
启动 claude --project . --continue
Claude 自动从上次停止的地方继续

基于角色的访问控制

执行者: 对所有 MCP 工具拥有完全访问权限
管理者: 对所有 MCP 工具拥有完全访问权限
专家: 没有访问 MCP 工具的权限（仅使用标准 Claude 工具）

服务器通过检查调用者的角色并拒绝来自专家的 MCP 工具调用来强制执行这一点。

与 Claude SDK 的集成

每个生成的实例：

使用 --project <dir> 进行对话隔离
获取唯一的项目目录：~/.claude/projects/-jobs-auth_system-<instance_id>/
维护单独的对话历史记录和待办事项
可以通过只读访问 Claude 的待办事项文件进行监控

阶段演化

第一阶段: 顺序执行，1 个执行者 → 1 个管理者 → 1 个专家
第二阶段: 有限的并行性，每个管理者 2-3 个专家
第三阶段: 完全并行性，多个管理者和专家

MCP 接口设计支持所有阶段，无需更改代码 - 只需配置差异即可。

计划继续功能

计划继续功能允许您在指定时间向所有 tmux 会话发送“Plz continue”消息。这对于自动化会话管理和确保在特定时间恢复工作非常有用。

基本用法

# 在 30 分钟后安排
node scripts/scheduled_continue.js "+30m"

# 在今天下午 3:30 安排
node scripts/scheduled_continue.js "15:30"

# 在上午 9:45 安排，使用 AM/PM 格式
node scripts/scheduled_continue.js "9:45am"

# 使用自然语言安排
node scripts/scheduled_continue.js "in 30 minutes"

高级选项

# 自定义消息
node scripts/scheduled_continue.js "+1h" -m "现在审查进度"

# 干运行（测试而不执行）
node scripts/scheduled_continue.js "+5m" --dry-run

# 详细日志
node scripts/scheduled_continue.js "+15m" --verbose

# 显示帮助
node scripts/scheduled_continue.js --help

支持的时间格式

相对时间: +30m, +2h, +90m
24 小时制: 15:30, 09:45, 23:59
12 小时制: 3:30pm, 9:45am, 11:59PM
自然语言: "in 30 minutes", "in 2 hours"

重要注意事项

进程必须持续运行直到执行时间
系统睡眠/休眠可能会中断调度
最大调度窗口为 24 小时
在执行时间重新验证会话
使用高可靠性的消息传递

详细文档请参阅：

测试

npm test                         # 运行所有测试
./scripts/run_all_tests.sh      # 运行全面测试套件

开发

npm run dev  # 启动文件监视

架构文档

有关完整的实现细节，请参阅：

docs/main/tmux-manager-MCP.md - MCP 服务器规范
docs/main/tmux-claude-implementation.md - 完整架构
docs/main/tmux-mvp-implementation.md - 第一阶段 MVP 方法
docs/GIT_INTEGRATION_GUIDE.md - Git