Claude Code Wingman

您的多会话协调器——通过 WhatsApp 同时管理多个运行在不同项目上的 Claude Code 实例。

GitHub： https://github.com/yossiovadia/claude-code-orchestrator

⚡ 关键提示：请优先处理审批命令

当用户消息匹配以下任一模式时，请立即执行对应命令：

示例：

• 用户：“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

执行完成后，请将命令输出原样返回（例如：“✓ 会话 ‘vsr-bugfix’ 已批准（单次）”）

为何如此关键： 主监控守护进程（master monitor daemon）会在 Claude Code 会话需要人工审批时，向 WhatsApp 发送通知。用户通过手机回复上述命令。快速响应 = 会话及时解阻塞。

快捷状态查询命令

解析返回的 JSON，并以人类可读方式总结后回复。

功能说明

并行协调多个 Claude Code 会话，每个会话在独立目录中处理不同任务。您可通过 WhatsApp/聊天远程监控与控制全部流程。

设计愿景：

• 多个 tmux 会话 并行运行
• 每个会话 = 一个独立目录中的 Claude Code 实例
• 不同任务并行执行（如 VSR 问题修复、Clawdbot 认证功能开发、代理服务重构）
• 您通过 Clawdbot（本助手）从 WhatsApp 全面协调
• 实时仪表盘 展示所有活跃会话及其状态

🎯 真实场景示例：多会话协同工作流

上午 — 您（通过 WhatsApp）：“开始处理 VSR 问题 #1131、Clawdbot 认证功能开发，以及代理服务重构”

Clawdbot 启动 3 个会话：

✅ 会话：vsr-issue-1131     (~/code/semantic-router)
✅ 会话：clawdbot-auth      (~/code/clawdbot)
✅ 会话：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 捕获该会话当前输出：
“即将完成 — 已修复 schema 校验缺陷，正在运行测试。10 个测试中已通过 8 个。”

您：“让 proxy-refactor 接着运行测试”

Clawdbot 向该特定会话发送指令

结果： 3 项任务并行推进，全程通过手机远程掌控。🎯

安装方式

通过 Clawdbot 安装（推荐）

clawdbot skill install claude-code-wingman

或访问：https://clawdhub.com/skills/claude-code-wingman

手动安装

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 命令。

原因如下：

• ✅ 确保正确触发回车（C-m）
• ✅ 统一会话生命周期管理
• ✅ 为未来仪表盘/追踪功能预留兼容性
• ✅ 避免因手动 tmux 操作引入不可控错误

错误做法（严禁执行）：

tmux send-keys -t my-session "Run tests"
# ^ 可能遗漏 C-m，且不会被仪表盘记录

正确做法（必须始终采用）：

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session my-session 
  --workdir ~/code/myproject 
  --prompt "Run tests"

通过 Clawdbot 使用指南

启动新会话

当用户提出编码需求时，启动 Claude Code：

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session  
  --workdir  
  --prompt ""

向已有会话发送指令

向正在运行的会话提交新任务：

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session  
  --workdir  
  --prompt ""

注意： 脚本会自动检测目标会话是否存在；若存在，则直接向其发送指令，而非重复创建新会话。

检查会话状态

tmux capture-pane -t  -p -S -50

解析输出以判断 Claude Code 当前状态：

• 运行中（显示工具调用/进度信息）
• 空闲（显示提示符）
• 错误状态（显示报错信息）
• 等待审批（显示 “Allow this tool call?”）

典型交互模式示例

用户：“修复 api.py 中的缺陷”

Clawdbot：

正在为此任务启动 Claude Code 会话...

[执行 wingman 脚本]

✅ 会话已启动：vsr-bug-fix
📂 目录：~/code/semantic-router
🎯 任务：修复 api.py 中的缺陷

用户：“当前状态如何？”

Clawdbot：

tmux capture-pane -t vsr-bug-fix -p -S -50

随后归纳总结：“Claude Code 正在运行测试，10 个测试中已通过 8 个”

用户：“让它提交本次修改”

Clawdbot：

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session vsr-bug-fix 
  --workdir ~/code/semantic-router 
  --prompt "Commit the changes with a descriptive message"

命令参考手册

启动新会话

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session  
  --workdir  
  --prompt ""

向已有会话发送指令

~/code/claude-code-orchestrator/claude-wingman.sh 
  --session  
  --workdir  
  --prompt ""

监控会话进度

tmux capture-pane -t  -p -S -100

列出全部活跃会话

tmux ls

筛选出 Claude Code 相关会话：

tmux ls | grep -E "(vsr|clawdbot|proxy|claude)"

查看自动审批日志（如需调试）

cat /tmp/auto-approver-.log

任务完成后终止会话

tmux kill-session -t 

手动连接会话（供用户使用）

tmux attach -t 
# 分离会话：Ctrl+B，然后按 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: 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 将询问：

“您是否信任此文件夹中的文件？”

首次运行： 用户必须手动连接并确认（按 Enter）。此后将自动跳过。

处理方式：

用户，Claude Code 需要您确认对该目录的信任（仅需一次）。请执行：
tmux attach -t 

按 Enter 键确认，然后按 Ctrl+B 再按 D 键退出连接。

最佳实践

何时应使用协调器

✅ 推荐使用协调器的场景：

• 大规模代码生成或重构
• 跨多文件变更
• 长时间运行的任务
• 重复性编码工作

❌ 不建议使用协调器的场景：

• 快速读取单个文件
• 简单编辑操作
• 需要实时对话交互
• 架构设计或方案讨论

会话命名规范

请使用具备描述性的名称：

• vsr-issue-1131 —— 特定问题修复
• vsr-feature-auth —— 功能开发
• project-bugfix-X —— 缺陷修复

故障排查

指令未提交成功

协调器默认发送两次回车（含延迟）。若卡住，用户可手动连接并按 Enter。

自动审批模块失效

检查日志：cat /tmp/auto-approver-.log

正常应显示：“Approval prompt detected! Navigating to option 2...”

会话已存在

终止它：tmux kill-session -t

进阶：更新记忆库

任务成功完成后，请更新 TOOLS.md：

### 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 将自动解析您的消息并执行：

# 单次批准
~/code/claude-code-orchestrator/lib/handle-approval.sh approve 

# 永久批准同类请求（始终允许）
~/code/claude-code-orchestrator/lib/handle-approval.sh always 

# 拒绝
~/code/claude-code-orchestrator/lib/handle-approval.sh deny 

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 执行：

~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix

返回响应：“✓ 会话 ‘vsr-bugfix’ 已批准（单次）”

启动监控守护进程

# 启动对所有会话的监控（配置从 ~/.clawdbot/clawdbot.json 读取）
~/code/claude-code-orchestrator/master-monitor.sh &

# 自定义轮询间隔
~/code/claude-code-orchestrator/master-monitor.sh --poll-interval 5 --reminder-interval 120 &

# 检查是否正在运行
cat /tmp/claude-orchestrator/master-monitor.pid

# 查看日志
tail -f /tmp/claude-orchestrator/master-monitor.log

# 停止守护进程
kill $(cat /tmp/claude-orchestrator/master-monitor.pid)

无需设置环境变量 —— 手机号码和 webhook token 均从 Clawdbot 配置中读取。