使用说明
Claude tmux MCP服务器
一个模型上下文协议（MCP）服务器，允许Claude Code读取、监视tmux窗格并与之交互——在跨多个终端会话工作时消除了复制/粘贴。
为什么存在
问题： 您正在不同的存储库（后端、前端、测试）上运行多个Claude Code会话。每个会话都对其他窗格中发生的事情视而不见。当Claude需要查看服务器日志或检查另一个代码库时，您可以手动复制/粘贴输出。
解决方案： 此MCP服务器使Claude可以直接访问tmux窗格。Claude可以读取服务器日志、监视测试输出、在实例之间共享结果以及生成可见代理，所有这些都不需要离开对话。
特性
🔍 窗格发现和阅读
- 列出所有按路径或命令筛选的tmux窗格
- 从任何窗格中捕获内容（最后N行）
- 使用正则表达式模式匹配监视窗格中的更改
- 获取详细的窗格元数据（维度、TTY、流程信息）
🤝 跨克劳德通信
- 通过tmux缓冲区在多个Claude实例之间共享上下文
- 用于发现、决策和分析的持久命名缓冲区
- 后台Claude分享API问题→ 前端Claude读取并验证
- 无需手动复制/粘贴即可进行协调
👁️ 可见代理执行
- 在可见的tmux窗格中生成代理（不再有不可见的后台代理！）
- 观察代理实时工作
- 使用智能布局并行执行代理
- 试剂完成后易于清理
⚡ 自动化工作流程
- Slash命令：
/vagent和/vagents用于快速产卵 - 常见模式的MCP提示模板
- 可配置的自动窗格创建，带有关键字检测功能
- 任务协调和依赖性跟踪
🔒 缺省巩固安全
- 读取自动批准的操作
- 写入操作（发送命令）需要用户批准
- 严格的输入验证可防止命令注入
- 仅对用户的tmux会话进行沙盒处理
快速开始
安装
# Clone the repository
git clone https://github.com/MMcintire96/claude-tmux.git
cd claude-tmux
# Install and build
npm install
npm run build
# Register with Claude Code
claude mcp add claude-tmux \
node $(pwd)/dist/index.js
# Restart Claude Code
pkill -f claude && claude
看 安装.md 详细的安装指南和故障排除。
第一步
问克劳德：
List all tmux panes
Claude将在所有会话中显示您的所有tmux窗格。
Read the last 50 lines from pane %123
Claude将捕获并向您显示窗格内容。
/vagent search for TODO comments
Claude将创建一个可见的窗格，并生成一个可以实时查看的代理！
使用示例
读取服务器日志
你：
后端服务器中显示了哪些错误？
克劳德：
I'll check the backend server pane for errors.
[Uses tmux_list_panes to find backend server]
[Uses tmux_capture_pane to read logs]
I found 3 errors in the last 100 lines:
1. Line 45: TypeError: Cannot read property 'id' of undefined
2. Line 67: Database connection timeout
3. Line 89: Rate limiter not configured for /api/auth
克罗斯-克劳德协调
后端Claude（第1节）：
在后端搜索身份验证漏洞
[Finds 3 SQL injection risks]
[Uses tmux_write_buffer to share findings]
I've shared my findings in buffer "claude-backend-security-2025-11-25".
The frontend Claude can read this to check if the UI validates properly.
前端克劳德（第2节）：
检查我们是否正确处理后端身份验证错误
[Uses tmux_read_buffer to get backend findings]
[Reads: "3 SQL injection risks found in auth endpoints"]
I can see the backend found SQL injection risks in:
- /api/auth/login
- /api/auth/refresh
- /api/users/:id
Let me check if the frontend validates input before sending...
生成可见代理
你：
/对安全漏洞的模糊搜索
克劳德：
Creating agent pane for security vulnerability search...
[Creates pane %150 with tmux_split_pane]
[Spawns security scanning agent in that pane]
Agent pane %150 created. You can watch the security scan in the bottom pane.
您的屏幕：
┌─────────────────────────────────────┐
│ Claude Code Session │
│ │
├─────────────────────────────────────┤
│ === Agent: security-vuln-scan === │
│ Scanning src/ directory... │
│ Found 145 files to analyze │
│ Checking auth.ts for SQL injection..│
│ Checking api.ts for XSS... │
│ ... │
└─────────────────────────────────────┘
并行代理
你：
/vagents在后端搜索bug，在前端搜索类型错误
克劳德：
Creating 2 agent panes side-by-side...
[Creates panes %151 and %152]
[Spawns both agents in parallel]
Agents running:
- backend-bug-search (pane %151)
- frontend-type-errors (pane %152)
Both visible in split panes. I'll report when they complete.
可用工具
MCP服务器提供4类17个工具：
窗格管理（5个工具）
tmux_list_panes-按路径或命令发现窗格tmux_capture_pane-阅读窗格内容tmux_send_command-在窗格中执行命令（需要用户批准）tmux_watch_pane-监控变化tmux_get_pane_info-详细窗格元数据
缓冲区通信（4个工具）
tmux_write_buffer-与其他Claude实例共享上下文tmux_read_buffer-访问共享上下文tmux_list_buffers-发现可用缓冲区tmux_delete_buffer-清理缓冲区
Agent Panes（4个工具）
tmux_split_pane-为代理创建可见窗格tmux_kill_pane-清理窗格tmux_resize_pane-调整窗格大小tmux_select_pane-焦点特定窗格
资源（4个资源）
tmux://sessions-所有tmux会话列表tmux://pane/{target}/content-直接访问窗格内容
看 API 文档 详细参数和示例。
Slash命令
两个自定义斜线命令使生成可见代理变得容易：
/vagent <task>
在可见窗格中生成单个代理。
示例：
/vagent search for authentication bugs
/vagent analyze the database schema
/vagent find all deprecated APIs
/vagents <tasks>
并行生成多个代理，每个代理都在自己的窗格中。
示例：
/vagents search backend AND search frontend
/vagents 3 search for security vulnerabilities
/vagents analyze auth AND analyze API AND analyze database
看 工作流_INTEGRATION.md 先进的模式。
MCP提示
三个内置提示提供结构化的工作流程：
spawn-visible-agent
Use prompt: spawn-visible-agent
task: "search for SQL injection vulnerabilities"
agent_type: "Explore"
pane_size: 40
spawn-parallel-agents
Use prompt: spawn-parallel-agents
tasks: ["search backend", "search frontend", "analyze API"]
layout: "grid"
monitor-agent-panes
Use prompt: monitor-agent-panes
显示所有正在运行的代理的状态及其进度和输出。
配置
编辑 agent-config.json 要自定义行为：
{
"agent_panes": {
"auto_create": true, // Auto-create panes for agents
"auto_cleanup": false, // Auto-kill panes when done
"default_layout": {
"direction": "vertical",
"size": 30
},
"keywords": {
"enabled": true,
"triggers": ["search for", "find all", "analyze for"]
}
},
"cleanup": {
"keep_on_error": true, // Keep panes if agent errors
"auto_kill_on_complete": false
}
}
看 配置指南 对于所有选项。
用例
多回购开发
在每个仓库（后端、前端、服务）中运行Claude Code。每个克劳德都可以：
- 从其他服务读取日志
- 共享API合同变更
- 跨仓库协调测试
- 监控构建输出
安全性审计
生成并行安全代理：
- 后端代理扫描SQL注入
- 前端代理检查XSS
- API代理验证速率限制
- 所有代理通过缓冲区共享发现
调试
Claude监视多个窗格：
- 服务器在一个窗格中登录
- 在另一个中测试输出
- 第三次数据库查询
- 关联所有来源的错误
代理工作流
使代理可见：
- 看看特工们到底在做什么
- 调试代理行为
- 理解代理推理
- 通过透明度信任系统
建筑
┌─────────────────────────────────────────────┐
│ Claude Code (MCP Client) │
├─────────────────────────────────────────────┤
│ MCP Protocol (stdio transport) │
├─────────────────────────────────────────────┤
│ Claude tmux MCP Server │
│ ┌─────────────────────────────────────────┐ │
│ │ Tools (17 total) │ │
│ │ - Pane management │ │
│ │ - Buffer communication │ │
│ │ - Agent panes │ │
│ └─────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────┐ │
│ │ Resources (4 total) │ │
│ │ - Sessions list │ │
│ │ - Pane content access │ │
│ └─────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────┐ │
│ │ Prompts (3 total) │ │
│ │ - spawn-visible-agent │ │
│ │ - spawn-parallel-agents │ │
│ │ - monitor-agent-panes │ │
│ └─────────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│ tmux (command execution via execFile) │
├─────────────────────────────────────────────┤
│ tmux Sessions & Panes │
│ ┌──────────┬──────────┬──────────┐ │
│ │ Backend │ Frontend │ Testing │ │
│ │ Claude │ Claude │ Claude │ │
│ └──────────┴──────────┴──────────┘ │
└─────────────────────────────────────────────┘
文档
- 安装.md -完整的安装指南
- 快速引用.md -一页备忘单
- 工作流_INTEGRATION.md -自动化工作流程指南
- HOW_TO_USE_AGENT_PANES.md -实用代理模式
- AGENT_PANES_GUIDE.md -技术参考
- CROSS_CLAUDE_GUIDE.md -多实例协调
- 多元素_内容_分析.md -未来的增强功能
需求
- Node.js 18.0.0或更高
- 子速率复用器 2.0或更高
- 克劳德代码 （桌面或CLI）
- 操作系统：Linux、macOS或Windows（WSL2）
项目结构
claude-tmux/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── types.ts # Zod schemas and types
│ ├── tmux-client.ts # tmux command wrapper
│ ├── agent-config.ts # Configuration system
│ ├── tools/ # 17 MCP tools
│ │ ├── list-panes.ts
│ │ ├── capture-pane.ts
│ │ ├── send-command.ts
│ │ ├── monitor-pane.ts
│ │ ├── get-pane-info.ts
│ │ ├── write-buffer.ts
│ │ ├── read-buffer.ts
│ │ ├── list-buffers.ts
│ │ ├── delete-buffer.ts
│ │ ├── split-pane.ts
│ │ ├── kill-pane.ts
│ │ ├── resize-pane.ts
│ │ └── select-pane.ts
│ └── resources/
│ └── pane-provider.ts # Resource provider
├── .claude/
│ └── commands/
│ ├── vagent.md # /vagent slash command
│ └── vagents.md # /vagents slash command
├── scripts/
│ └── spawn-visible-agent.sh
├── dist/ # Compiled JavaScript
├── docs/ # Documentation
├── agent-config.json # Configuration file
├── package.json
├── tsconfig.json
└── README.md
安全
- 输入验证：所有参数均通过Zod模式验证
- 指挥安全：用途
execFile而不是exec防止外壳注射 - 靶点验证：严格的正则表达式可防止在窗格目标中注入命令
- 会话隔离：只能访问用户的tmux会话
- 用户批准：写入操作需要明确的权限
- 没有坚持：缓冲区存储在tmux内存中，而不是磁盘上（默认情况下）
看 安全.md 了解详情。
演出
- 轻量级：每个实例约20-30MB内存
- 快速：窗格操作的延迟最小
- 可扩展的：测试了50多个窗格，10多个Claude会话
- 无磁盘I/O：使用tmux会话内存
故障排除
常见问题
“找不到MCP服务器”
# Check registration
claude mcp list
# Verify path is absolute in ~/.config/claude/config.json
cat ~/.config/claude/config.json | grep claude-tmux -A 3
# Rebuild and restart
npm run build && pkill -f claude && claude
“找不到tmux服务器”
# Start tmux
tmux new-session -s test
# Verify tmux is installed
which tmux
Slash命令不起作用
# Verify commands exist
ls -la .claude/commands/
# Should see: vagent.md, vagents.md
看 安装.md 获取完整的故障排除指南。
许可证
MIT许可证-请参阅 许可证 了解详情。
如果此仓库有助于您的工作流程，请将其标记为星号！ ⭐
