介绍
# Claude Code Wingman
您的多会话协调器——管理多个同时在不同的项目上工作的 Claude Code 实例，全部通过 WhatsApp 完成。
**GitHub:** https://github.com/yossiovadia/claude-code-orchestrator
## ⚡ 关键：优先处理批准命令
**当用户消息匹配以下模式时，立即运行相应的命令：**
| 用户消息模式 | 要运行的命令 | |---------------------|----------------| | `approve <session>` | `~/code/claude-code-orchestrator/lib/handle-approval.sh approve <session>` | | `always <session>` | `~/code/claude-code-orchestrator/lib/handle-approval.sh always <session>` | | `deny <session>` | `~/code/claude-code-orchestrator/lib/handle-approval.sh deny <session>` |
**示例：** - 用户："approve vsr-bugfix" → 运行：`~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix` - 用户："always heartbeat-test" → 运行：`~/code/claude-code-orchestrator/lib/handle-approval.sh always heartbeat-test` - 用户："deny proxy-refactor" → 运行：`~/code/claude-code-orchestrator/lib/handle-approval.sh deny proxy-refactor`
**运行后，用命令输出响应**（例如，"✓ Session 'vsr-bugfix' approved (once)"）
**为什么这很关键：** 主监控守护进程会在 Claude Code 会话需要批准时发送 WhatsApp 通知。用户通过手机用这些命令进行响应。快速响应 = 解锁阻塞的会话。
### 快速状态命令
| 用户消息 | 要运行的命令 | |--------------|----------------| | `sessions` 或 `status` | `~/code/claude-code-orchestrator/lib/session-status.sh --all --json` | | `status <session>` | `~/code/claude-code-orchestrator/lib/session-status.sh <session> --json` |
解析 JSON 并以可读的摘要进行响应。
---
## 功能介绍
并行协调多个 Claude Code 会话，每个会话在不同目录中处理不同的任务。您可以通过 WhatsApp/聊天远程监控和控制一切。
**愿景：** - **多个 tmux 会话** 同时运行 - **每个会话 = 一个 Claude Code 实例** 在其各自的目录中 - **不同的任务** 并行进行（VSR 修复、Clawdbot 功能、代理重构） - **您通过 Clawdbot（本助手）在 WhatsApp 上协调一切** - **实时仪表板** 显示所有活动会话及其状态
## 🎯 现实世界示例：多会话协调
**早上 - 您（通过 WhatsApp）：** "开始处理 VSR 问题 #1131、Clawdbot 认证功能，并重构代理"
**Clawdbot 启动 3 个会话：** ``` ✅ Session: vsr-issue-1131 (~/code/semantic-router) ✅ Session: clawdbot-auth (~/code/clawdbot) ✅ Session: proxy-refactor (~/code/claude-code-proxy) ```
**午餐期间 - 您：** "给我看仪表板"
**Clawdbot：** ``` ┌─────────────────────────────────────────────────────────┐ │ Active Claude Code Sessions │ ├─────────────────┬──────────────────────┬────────────────┤ │ vsr-issue-1131 │ semantic-router │ ✅ Working │ │ clawdbot-auth │ clawdbot │ ✅ Working │ │ proxy-refactor │ claude-code-proxy │ ⏳ Waiting approval │ └─────────────────┴──────────────────────┴────────────────┘ ```
**您：** "VSR 问题进展如何？"
**Clawdbot 捕获会话输出：** "快完成了 - 修复了架构验证错误，正在运行测试。8/10 测试通过。"
**您：** "告诉 proxy-refactor 下一步运行测试"
**Clawdbot 发送命令** 到该特定会话。
**结果：** 3 个并行任务，从您的手机完全远程控制。🎯
## 安装
### 通过 Clawdbot（推荐）
```bash clawdbot skill install claude-code-wingman ```
或访问：https://clawdhub.com/skills/claude-code-wingman
### 手动安装
```bash cd ~/code git clone https://github.com/yossiovadia/claude-code-orchestrator.git cd claude-code-orchestrator chmod +x *.sh lib/*.sh ```
### 要求
- `claude` CLI（Claude Code） - `tmux`（终端复用器） - `jq`（JSON 处理器）
## 核心理念：始终使用 Wingman 脚本
**关键：** 与 Claude Code 会话交互时，始终使用 wingman 脚本（`claude-wingman.sh`）。永远不要直接运行原始 tmux 命令。
**原因：** - ✅ 确保正确的 Enter 键处理（C-m） - ✅ 一致的会话管理 - ✅ 面向未来的仪表板/跟踪功能 - ✅ 避免手动 tmux 命令导致的错误
**错误（不要这样做）：** ```bash tmux send-keys -t my-session "Run tests" # ^ Might forget C-m, won't be tracked in dashboard ```
**正确（始终这样做）：** ```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session my-session \ --workdir ~/code/myproject \ --prompt "Run tests" ```
---
## 从 Clawdbot 使用
### 启动新会话
当用户要求编码工作时，启动 Claude Code：
```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session <session-name> \ --workdir <project-directory> \ --prompt "<task description>" ```
### 向现有会话发送命令
要向已在运行的会话发送新任务：
```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session <existing-session-name> \ --workdir <same-directory> \ --prompt "<new task>" ```
**注意：** 脚本会检测会话是否存在，并将命令发送到该会话，而不是创建重复的会话。
### 检查会话状态
```bash tmux capture-pane -t <session-name> -p -S -50 ```
解析输出以确定 Claude Code 是否： - 正在工作（显示工具调用/进度） - 空闲（显示提示符） - 错误状态（显示错误） - 等待批准（显示 "Allow this tool call?"）
---
## 示例模式
**用户：** "修复 api.py 中的错误"
**Clawdbot：** ``` Spawning Claude Code session for this...
[Runs wingman script]
✅ Session started: vsr-bug-fix 📂 Directory: ~/code/semantic-router 🎯 Task: Fix bug in api.py ```
**用户：** "状态如何？"
**Clawdbot：** ```bash tmux capture-pane -t vsr-bug-fix -p -S -50 ```
然后总结："Claude Code 正在运行测试，8/10 通过"
**用户：** "告诉它提交更改"
**Clawdbot：** ```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session vsr-bug-fix \ --workdir ~/code/semantic-router \ --prompt "Commit the changes with a descriptive message" ```
## 命令参考
### 启动新会话 ```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session <name> \ --workdir <dir> \ --prompt "<task>" ```
### 向现有会话发送命令 ```bash ~/code/claude-code-orchestrator/claude-wingman.sh \ --session <existing-session> \ --workdir <same-dir> \ --prompt "<new command>" ```
### 监控会话进度 ```bash tmux capture-pane -t <session-name> -p -S -100 ```
### 列出所有活动会话 ```bash tmux ls ```
筛选 Claude Code 会话： ```bash tmux ls | grep -E "(vsr|clawdbot|proxy|claude)" ```
### 查看自动批准日志（如需要） ```bash cat /tmp/auto-approver-<session-name>.log ```
### 完成后终止会话 ```bash tmux kill-session -t <session-name> ```
### 手动附加（供用户使用） ```bash tmux attach -t <session-name> # Detach: Ctrl+B, then D ```
---
## 路线图：多会话仪表板（即将推出）
**计划功能：**
### `wingman dashboard` 显示所有活动 Claude Code 会话： ``` ┌─────────────────────────────────────────────────────────┐ │ Active Claude Code Sessions │ ├─────────────────┬──────────────────────┬────────────────┤ │ Session │ Directory │ Status │ ├─────────────────┼──────────────────────┼────────────────┤ │ vsr-issue-1131 │ ~/code/semantic-... │ ✅ Working │ │ clawdbot-feat │ ~/code/clawdbot │ ⏳ Waiting approval │ │ proxy-refactor │ ~/code/claude-co... │ ❌ Error │ └─────────────────┴──────────────────────┴────────────────┘
Total: 3 sessions | Working: 1 | Waiting: 1 | Error: 1 ```
### `wingman status <session>` 特定会话的详细状态： ``` Session: vsr-issue-1131 Directory: ~/code/semantic-router Started: 2h 15m ago Last activity: 30s ago Status: ✅ Working Current task: Running pytest tests Progress: 8/10 tests passing ```
### 会话注册表 - 持久跟踪（在 Clawdbot 重启后仍然存在） - 存储会话元数据的 JSON 文件 - 自动清理死会话
**目前：** 直接使用 tmux 命令，但始终通过 wingman 脚本发送命令！
## 工作流程
1. **用户请求编码工作**（修复错误、添加功能、重构等） 2. **Clawdbot 通过协调器脚本启动 Claude Code** 3. **自动批准器在后台处理权限** 4. **Clawdbot 监控并报告进度** 5. **用户可以随时附加** 以直接查看/控制 6. **Claude Code 自主完成工作** ✅
## 信任提示（仅首次）
在新目录中运行时，Claude Code 会询问： > "Do you trust the files in this folder?"
**首次运行：** 用户必须附加并批准（按 Enter）。之后，它是自动的。
**处理方法：** ``` User, Claude Code needs you to approve the folder trust (one-time). Please run: tmux attach -t <session-name>
Press Enter to approve, then Ctrl+B followed by D to detach. ```
## 最佳实践
### 何时使用协调器
✅ **对以下情况使用协调器：** - 大量代码生成/重构 - 多文件更改 - 长时间运行的任务 - 重复性编码工作
❌ **不要对以下情况使用协调器：** - 快速文件读取 - 简单编辑 - 需要对话时 - 规划/设计讨论
### 会话命名
使用描述性名称： - `vsr-issue-1131` - 特定问题工作 - `vsr-feature-auth` - 功能开发 - `project-bugfix-X` - 错误修复
## 故障排除
### 提示未提交
协调器会发送两次 Enter 并有延迟。如果卡住，用户可以附加并手动按 Enter。
### 自动批准器不工作
检查日志：`cat /tmp/auto-approver-<session-name>.log`
应该看到："Approval prompt detected! Navigating to option 2..."
### 会话已存在
终止它：`tmux kill-session -t <name>`
## 高级：更新记忆
成功的任务后，更新 `TOOLS.md`：
```markdown ### Recent Claude Code Sessions - 2026-01-26: VSR AWS check - verified vLLM server running ✅ - Session pattern: vsr-* for semantic-router work ```
## 专业提示
- **并行会话：** 在不同的会话中同时运行多个任务 - **一致的命名：** 使用项目前缀（vsr-、myapp- 等） - **定期监控：** 每隔几分钟检查进度 - **让它完成：** 不要过早终止会话，让 Claude Code 完成任务
---
## 🔔 批准处理（WhatsApp 集成）
主监控守护进程会在会话需要批准时发送 WhatsApp 通知。使用这些命令处理它们：
### 批准命令（来自 WhatsApp）
当您收到批准通知时，回复：
**Clawdbot 解析您的消息并运行：** ```bash # Approve once ~/code/claude-code-orchestrator/lib/handle-approval.sh approve <session-name>
# Approve all similar (always) ~/code/claude-code-orchestrator/lib/handle-approval.sh always <session-name>
# Deny ~/code/claude-code-orchestrator/lib/handle-approval.sh deny <session-name> ```
### WhatsApp 流程示例
**收到通知：** ``` 🔒 Session 'vsr-bugfix' needs approval
Bash(rm -rf ./build && npm run build)
Reply with: • approve vsr-bugfix - Allow once • always vsr-bugfix - Allow all similar • deny vsr-bugfix - Reject ```
**您回复：** "approve vsr-bugfix"
**Clawdbot：** ```bash ~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix ```
**响应：** "✓ Session 'vsr-bugfix' approved (once)"
### 启动监控守护进程
```bash # Start monitoring all sessions (reads config from ~/.clawdbot/clawdbot.json) ~/code/claude-code-orchestrator/master-monitor.sh &
# With custom intervals ~/code/claude-code-orchestrator/master-monitor.sh --poll-interval 5 --reminder-interval 120 &
# Check if running cat /tmp/claude-orchestrator/master-monitor.pid
# View logs tail -f /tmp/claude-orchestrator/master-monitor.log
# Stop the daemon kill $(cat /tmp/claude-orchestrator/master-monitor.pid) ```
不需要环境变量——手机和 webhook 令牌从 Clawdbot 配置中读取。