Claude Code Wingman

**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-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. **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:**
```
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.

### Auto-Approver Not Working
Check logs: `cat /tmp/auto-approver-<session-name>.log`

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

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

### Start the Monitor Daemon

```bash
# Start monitoring all sessions (reads config from ~/.clawdbot/clawdbot.json)
~/code/claude-code-orchestrator/master-monitor.sh &

# With custom intervals
~/code/claude-code-orchestrator/master-monitor.sh --poll-interval 5 --reminder-interval 120 &

# Check if running
cat /tmp/claude-orchestrator/master-monitor.pid

# View logs
tail -f /tmp/claude-orchestrator/master-monitor.log

# Stop the daemon
kill $(cat /tmp/claude-orchestrator/master-monitor.pid)
```

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