# Claude Code Wingman

> Your Claude Code wingman - orchestrate multiple Claude Code sessions across projects, monitor them all from WhatsApp

- Skill: `yossiovadia/claude-code-wingman` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds add yossiovadia/claude-code-wingman`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yossiovadia/claude-code-wingman/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yossiovadia (https://skillmd.com/u/yossiovadia)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/yossiovadia/claude-code-wingman

---


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

```bash
~/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:**
```bash
tmux new-session -d -s my-session
tmux send-keys -t my-session "claude" Enter
```

**RIGHT - Always do this:**
```bash
~/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)

```bash
clawdbot skill install claude-code-wingman
```

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

### Manual Installation

```bash
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)

## Usage from Clawdbot

### Start a New Session

When a user asks for coding work, use the wingman script:

```bash
~/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:

```bash
~/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

```bash
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:**
```bash
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:**
```bash
~/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
```bash
~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <name> \
  --workdir <dir> \
  --prompt "<task>"
```

### Send Command to Existing Session
```bash
~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <existing-session> \
  --workdir <same-dir> \
  --prompt "<new command>"
```

### Monitor Session Progress
```bash
tmux capture-pane -t <session-name> -p -S -100
```

### List All Active Sessions
```bash
tmux ls
```

Filter for Claude Code sessions:
```bash
tmux ls | grep -E "(vsr|clawdbot|proxy|claude)"
```

### View Monitor Log
```bash
tail -f /tmp/claude-orchestrator/master-monitor.log
```

### Kill Session When Done
```bash
tmux kill-session -t <session-name>
```

### Attach Manually (for user)
```bash
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

1. **User requests coding work** (fix bug, add feature, refactor, etc.)
2. **Clawdbot spawns Claude Code** via orchestrator script
3. **Master monitor watches** and sends WhatsApp notifications for approvals
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:**
```
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`:

```markdown
### 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:**
```bash
# 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:**
```bash
~/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.