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