claude-code-wingman

What this skill does

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

---

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

## 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):**
```bash
tmux send-keys -t my-session "Run tests"
# ^ Might forget C-m, won't be tracked in dashboard
```

**Right (ALWAYS DO THIS):**
```bash
~/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:

```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 Auto-Approver Log (if needed)
```bash
cat /tmp/auto-approver-<session-name>.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-rout