--- name: claude-code-wingman description: Your Claude Code wingman - orchestrate multiple Claude Code sessions across projects, monitor them all from WhatsApp metadata: {"clawdbot":{"emoji":"🦅","requires":{"anyBins":["claude","tmux"]}}} ---

Claude Code Wingman

Your multi-session orchestrator - manage multiple Claude Code instances working on different projects simultaneously, all from WhatsApp.

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

⚡ CRITICAL: Handle Approval Commands First

When a user message matches these patterns, IMMEDIATELY run the corresponding command:

| User Message Pattern | Command to Run | |---------------------|----------------| | approve | ~/code/claude-code-orchestrator/lib/handle-approval.sh approve | | always | ~/code/claude-code-orchestrator/lib/handle-approval.sh always | | deny | ~/code/claude-code-orchestrator/lib/handle-approval.sh deny |

Examples:

• User: "approve vsr-bugfix" → Run: ~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix
• User: "always heartbeat-test" → Run: ~/code/claude-code-orchestrator/lib/handle-approval.sh always heartbeat-test
• User: "deny proxy-refactor" → Run: ~/code/claude-code-orchestrator/lib/handle-approval.sh deny proxy-refactor

After running, respond with the command output (e.g., "✓ Session 'vsr-bugfix' approved (once)")

Why this is critical: The master monitor daemon sends WhatsApp notifications when Claude Code sessions need approval. The user responds with these commands from their phone. Fast response = unblocked sessions.

Quick Status Commands

| User Message | Command to Run | |--------------|----------------| | sessions or status | ~/code/claude-code-orchestrator/lib/session-status.sh --all --json | | status | ~/code/claude-code-orchestrator/lib/session-status.sh --json |

Parse the JSON and respond with a human-readable summary.

---

What It Does

Orchestrates multiple Claude Code sessions in parallel, each working on different tasks in different directories. You monitor and control everything remotely via WhatsApp/chat.

The Vision:

• Multiple tmux sessions running simultaneously
• Each session = one Claude Code instance in its own directory
• Different tasks happening in parallel (VSR fixes, Clawdbot features, proxy refactoring)
• You orchestrate everything via Clawdbot (this assistant) from WhatsApp
• Real-time dashboard showing all active sessions and their status

🎯 Real-World Example: Multi-Session Orchestration

Morning - You (via WhatsApp): "Start work on VSR issue #1131, Clawdbot authentication feature, and refactor the proxy"

Clawdbot spawns 3 sessions:

✅ Session: vsr-issue-1131     (~/code/semantic-router)
✅ Session: clawdbot-auth      (~/code/clawdbot)
✅ Session: proxy-refactor     (~/code/claude-code-proxy)

During lunch - You: "Show me the dashboard"

Clawdbot:

┌─────────────────────────────────────────────────────────┐
│ Active Claude Code Sessions                             │
├─────────────────┬──────────────────────┬────────────────┤
│ vsr-issue-1131  │ semantic-router      │ ✅ Working     │
│ clawdbot-auth   │ clawdbot             │ ✅ Working     │
│ proxy-refactor  │ claude-code-proxy    │ ⏳ Waiting approval │
└─────────────────┴──────────────────────┴────────────────┘

You: "How's the VSR issue going?"

Clawdbot captures session output: "Almost done - fixed the schema validation bug, running tests now. 8/10 tests passing."

You: "Tell proxy-refactor to run tests next"

Clawdbot sends command to that specific session.

Result: 3 parallel tasks, full remote control from your phone. 🎯

Installation

Via Clawdbot (Recommended)

clawdbot skill install claude-code-wingman

Or visit: https://clawdhub.com/skills/claude-code-wingman

Manual Installation

cd ~/code
git clone https://github.com/yossiovadia/claude-code-orchestrator.git
cd claude-code-orchestrator
chmod +x *.sh lib/*.sh

Requirements

• claude CLI (Claude Code)
• tmux (terminal multiplexer)
• jq (JSON processor)

Core Philosophy: Always Use the Wingman Script

CRITICAL: When interacting with Claude Code sessions, ALWAYS use the wingman script (claude-wingman.sh). Never run raw tmux commands directly.

Why:

• ✅ Ensures proper Enter key handling (C-m)
• ✅ Consistent session management
• ✅ Future-proof for dashboard/tracking features
• ✅ Avoids bugs from manual tmux commands

Wrong (DON'T DO THIS):

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

Right (ALWAYS DO THIS):

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

---

Usage from Clawdbot

Start a New Session

When a user asks for coding work, spawn Claude Code:

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <session-name> \
  --workdir <project-directory> \
  --prompt "<task description>"

Send Command to Existing Session

To send a new task to an already-running session:

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

Note: The script detects if the session exists and sends the command to it instead of creating a duplicate.

Check Session Status

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

Parse the output to determine if Claude Code is:

• Working (showing tool calls/progress)
• Idle (showing prompt)
• Error state (showing errors)
• Waiting for approval (showing "Allow this tool call?")

---

Example Patterns

User: "Fix the bug in 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

User: "What's the status?"

Clawdbot:

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

Then summarize: "Claude Code is running tests now, 8/10 passing"

User: "Tell it to commit the changes"

Clawdbot:

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

Commands Reference

Start New Session

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <name> \
  --workdir <dir> \
  --prompt "<task>"

Send Command to Existing Session

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

Monitor Session Progress

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

List All Active Sessions

tmux ls

Filter for Claude Code sessions:

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

View Auto-Approver Log (if needed)

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

Kill Session When Done

tmux kill-session -t <session-name>

Attach Manually (for user)

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

---

Roadmap: Multi-Session Dashboard (Coming Soon)

Planned features:

...