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:

Examples:

• - User: "approve vsr-bugfix" → Run: INLINECODE6
• User: "always heartbeat-test" → Run: INLINECODE7
• User: "deny proxy-refactor" → Run: INLINECODE8

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

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:
CODEBLOCK0

During lunch - You: "Show me the dashboard"

Clawdbot:
CODEBLOCK1

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)

CODEBLOCK2

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

Manual Installation

CODEBLOCK3

Requirements

• - claude CLI (Claude Code)
• INLINECODE15 (terminal multiplexer)
• INLINECODE16 (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):
CODEBLOCK4

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:

CODEBLOCK6

Send Command to Existing Session

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

CODEBLOCK7

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

Check Session Status

CODEBLOCK8

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:
CODEBLOCK9

User: "What's the status?"

Clawdbot:
CODEBLOCK10

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

User: "Tell it to commit the changes"

Clawdbot:
CODEBLOCK11

Commands Reference

Start New Session

Send Command to Existing Session

Monitor Session Progress

List All Active Sessions

Filter for Claude Code sessions:
CODEBLOCK16

View Auto-Approver Log (if needed)

Kill Session When Done

Attach Manually (for user)

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

Roadmap: Multi-Session Dashboard (Coming Soon)

Planned features:

wingman dashboard

wingman status <session>

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

1. 1. User requests coding work (fix bug, add feature, refactor, etc.)
2. Clawdbot spawns Claude Code via orchestrator script
3. Auto-approver handles permissions in background
4. Clawdbot monitors and reports progress
5. User can attach anytime to see/control directly
6. 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:
CODEBLOCK22

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
• INLINECODE21 - feature development
• INLINECODE22 - bug fixes

Troubleshooting

Prompt Not Submitting

Auto-Approver Not Working

Should see: "Approval prompt detected! Navigating to option 2..."

Session Already Exists

Advanced: Update Memory

After successful tasks, update TOOLS.md:

CODEBLOCK23

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:
CODEBLOCK24

Example WhatsApp Flow

Notification received:
CODEBLOCK25

You reply: "approve vsr-bugfix"

Clawdbot:
CODEBLOCK26

Response: "✓ Session 'vsr-bugfix' approved (once)"

Start the Monitor Daemon

CODEBLOCK27

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