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

运行后，回应命令输出（例如："✓ Session 'vsr-bugfix' approved (once)"）

为何这很关键：当Claude Code会话需要批准时，主监控守护程序会发送WhatsApp通知。用户从手机回复这些命令。快速响应 = 解除阻塞的会话。

快速状态命令

解析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捕获会话输出："快完成了——修复了模式验证错误，现在正在运行测试。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

要求

• claudeCLI（Claude Code）
• tmux（终端多路复用器）
• jq（JSON处理器）

核心理念：始终使用Wingman脚本

重要提示：与Claude Code会话交互时，务必使用wingman脚本（claude-wingman.sh）。切勿直接运行原始的tmux命令。

原因：

• ✅ 确保正确处理回车键（C-m）
• ✅ 一致的会话管理
• ✅ 为仪表板/追踪功能做好未来兼容
• ✅ 避免手动tmux命令导致的错误

错误做法（切勿如此操作）：

tmux send-keys -t my-session "Run tests"
# ^ Might forget C-m, won't be tracked in dashboard

正确做法（务必如此操作）：

~/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 <session-name> \
  --workdir <project-directory> \
  --prompt "<task description>"

向现有会话发送命令

要向已运行的会话发送新任务：

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <existing-session-name> \
  --workdir <same-directory> \
  --prompt "<new task>"

注意：该脚本会检测会话是否存在，并将命令发送至该会话，而非创建重复会话。

检查会话状态

tmux capture-pane -t <session-name> -p -S -50

解析输出以确定Claude Code的状态：

• 工作中（显示工具调用/进度）
• 空闲状态（显示提示）
• 错误状态（显示错误信息）
• 等待批准（显示"是否允许此工具调用？"）

示例模式

用户："修复api.py中的bug"

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：

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 <name> \
  --workdir <dir> \
  --prompt "<task>"

向现有会话发送命令

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <existing-session> \
  --workdir <same-dir> \
  --prompt "<new command>"

监控会话进度

tmux capture-pane -t <session-name> -p -S -100

列出所有活跃会话

tmux ls

筛选Claude Code会话：

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

查看自动批准日志（如需）

cat /tmp/auto-approver-<session-name>.log

任务完成后终止会话

tmux kill-session -t <session-name>

手动附加（供用户使用）

tmux attach -t <session-name>
# Detach: Ctrl+B, then D

路线图：多会话仪表板（即将推出）

计划中的功能：

wingman 仪表板

显示所有活跃的 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 会询问：

"您信任此文件夹中的文件吗？"

首次运行：用户必须接入并批准（按回车键）。之后将自动运行。

处理方法：

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- 错误修复

故障排除

提示未提交

协调器会发送两次回车并带有延迟。如果卡住，用户可以手动连接并按回车键。

自动批准器不工作

检查日志：cat /tmp/auto-approver-<会话名称>.log

应看到："检测到批准提示！正在导航至选项 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 会解析您的消息并运行：

# 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：

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

“✓ 会话 'vsr-bugfix' 已批准（一次）”启动监控守护进程

无需环境变量 - 手机和webhook令牌将从Clawdbot配置中读取。

# 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)

No environment variables needed - phone and webhook token are read from Clawdbot config.