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 <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> |
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 <session> | ~/code/claude-code-orchestrator/lib/session-status.sh <session> --json |
Parse the JSON and respond with a human-readable summary.
⚠️ CRITICAL: Always Use the Wingman Script
NEVER create tmux sessions or run Claude Code directly. Always use the wingman script:
~/code/claude-code-orchestrator/claude-wingman.sh \ --session <session-name> \ --workdir <project-directory> \ --prompt "<task description>"
Why this is mandatory:
- •The wingman script auto-starts the master monitor daemon
- •Without it, you won't receive WhatsApp approval notifications
- •Raw tmux commands break the notification system
WRONG - Never do this:
tmux new-session -d -s my-session tmux send-keys -t my-session "claude" Enter
RIGHT - Always do this:
~/code/claude-code-orchestrator/claude-wingman.sh \ --session my-session \ --workdir ~/code/myproject \ --prompt "Fix the bug in api.py"
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
- •
claudeCLI (Claude Code) - •
tmux(terminal multiplexer) - •
jq(JSON processor)
Usage from Clawdbot
Start a New Session
When a user asks for coding work, use the wingman script:
~/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 Monitor Log
tail -f /tmp/claude-orchestrator/master-monitor.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:
wingman dashboard
Shows all active Claude Code sessions:
┌─────────────────────────────────────────────────────────┐ │ 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>
Detailed status for a specific 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
Session Registry
- •Persistent tracking (survives Clawdbot restarts)
- •JSON file storing session metadata
- •Auto-cleanup of dead sessions
For now: Use tmux commands directly, but always via the wingman script for sending commands!
Workflow
- •User requests coding work (fix bug, add feature, refactor, etc.)
- •Clawdbot spawns Claude Code via orchestrator script
- •Master monitor watches and sends WhatsApp notifications for approvals
- •Clawdbot monitors and reports progress
- •User can attach anytime to see/control directly
- •Claude Code does the work autonomously ✅
Trust Prompt (First Time Only)
When running in a new directory, Claude Code asks:
"Do you trust the files in this folder?"
First run: User must attach and approve (press Enter). After that, it's automatic.
Handle it:
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.
Best Practices
When to Use Orchestrator
✅ Use orchestrator for:
- •Heavy code generation/refactoring
- •Multi-file changes
- •Long-running tasks
- •Repetitive coding work
❌ Don't use orchestrator for:
- •Quick file reads
- •Simple edits
- •When conversation is needed
- •Planning/design discussions
Session Naming
Use descriptive names:
- •
vsr-issue-1131- specific issue work - •
vsr-feature-auth- feature development - •
project-bugfix-X- bug fixes
Troubleshooting
Prompt Not Submitting
The orchestrator sends Enter twice with delays. If stuck, user can attach and press Enter manually.
Not Receiving WhatsApp Notifications
Check monitor logs: tail -f /tmp/claude-orchestrator/master-monitor.log
Verify monitor is running: cat /tmp/claude-orchestrator/master-monitor.pid
Session Already Exists
Kill it: tmux kill-session -t <name>
Advanced: Update Memory
After successful tasks, update TOOLS.md:
### Recent Claude Code Sessions - 2026-01-26: VSR AWS check - verified vLLM server running ✅ - Session pattern: vsr-* for semantic-router work
Pro Tips
- •Parallel sessions: Run multiple tasks simultaneously in different sessions
- •Name consistently: Use project prefixes (vsr-, myapp-, etc.)
- •Monitor periodically: Check progress every few minutes
- •Let it finish: Don't kill sessions early, let Claude Code complete
🔔 Approval Handling (WhatsApp Integration)
The master monitor daemon sends WhatsApp notifications when sessions need approval. Handle them with these commands:
Approve Commands (from WhatsApp)
When you receive an approval notification, respond with:
Clawdbot parses your message and runs:
# 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>
Example WhatsApp Flow
Notification received:
🔒 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
You reply: "approve vsr-bugfix"
Clawdbot:
~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix
Response: "✓ Session 'vsr-bugfix' approved (once)"
The master monitor daemon starts automatically when the first wingman session is created. No manual setup needed.