Claude Code Wingman

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

Security Scan

The skill mostly does what it says (orchestrates Claude Code via tmux and notifies via WhatsApp), but there are several mismatches and risky behaviors (auto-approval, undeclared env/config access, and a background daemon) that are not declared in the registry metadata and deserve caution.

Purpose & Capability

The scripts and SKILL.md are coherent with the stated purpose (spawn Claude Code in tmux, monitor sessions, notify via WhatsApp). However the package metadata in the registry omits some actual runtime needs: SKILL.md and scripts require jq, curl and expect a Clawdbot webhook/phone configuration, but the registry lists only 'claude' and 'tmux' as required binaries and declares no required env/config paths. That mismatch (undeclared tooling and config file access) is a concern.

Instruction Scope

SKILL.md instructs the agent to run many shell scripts (start sessions, start approvers, run master-monitor, call lib/handle-approval.sh on WhatsApp commands). Those instructions cause the agent to: create tmux sessions, send keystrokes to those sessions, read and write files under /tmp and ~/.clawdbot, and make HTTP requests to webhook endpoints. The critical 'handle approval commands first' rule telling the agent to immediately run handle-approval.sh for matching messages gives the agent direct ability to execute local shell commands — this is consistent with the purpose but amplifies risk and should be explicitly declared.

Install Mechanism

There is no install spec in the registry (skill is instruction-only), but the bundle includes full scripts and manual-install instructions that clone a GitHub repo. No external arbitrary downloads or shorteners are used. The source URL is present in docs (GitHub), but the registry lists 'Source: unknown' / homepage none — that mismatch (packaged code vs registry source metadata) is notable but not outright malicious.

Credentials

Scripts optionally read or require CLAWDBOT_WEBHOOK_TOKEN, CLAWDBOT_PHONE, CLAWDBOT_CONFIG (~/.clawdbot/clawdbot.json) and allow overriding the webhook URL via env. None of these env vars or config paths are declared as required in the registry metadata. The skill will attempt to read the user's Clawdbot config and/or expect a webhook token/phone; that is access to user-specific credentials/config that should be declared and reviewed before install.

Persistence & Privilege

The package provides a master-monitor daemon script designed to run persistently (PID file, /tmp state dir, repeated notifications), and SKILL.md suggests installation into Clawdbot and restarting the gateway. The skill metadata does not set always:true, but the scripts are explicitly designed to be run as long-lived processes and to send external notifications. This persistence is not reflected in registry privilege metadata and should be considered when deciding to install.

What to consider before installing

Things to check before installing or running this skill: - Review the code yourself (especially auto-approver.sh, interactive-approver.sh, master-monitor.sh, and lib/send-notification.sh). The auto-approver will automatically approve 'Do you want' prompts and folder trust prompts, which may allow Claude Code to execute tools, write files, or run shell commands without further human confirmation. - Confirm where notifications go and who controls the webhook: lib/send-notification.sh will use CLAWDBOT_WEBHOOK_TOKEN, CLAWDBOT_PHONE or ~/.clawdbot/clawdbot.json and by default posts to http://127.0.0.1:18789/hooks/agent unless overridden. Make sure the webhook URL/token are under your control and not pointed at a remote endpoint you don't trust. - Be aware of undeclared requirements: scripts use jq, curl and expect access to ~/.clawdbot/clawdbot.json and /tmp state files. The registry metadata lists only 'claude' and 'tmux' — verify you have or want to grant these additional accesses. - Prefer interactive mode: avoid running with --auto unless you fully trust the environment and understand that prompts (including ones that could allow running arbitrary tool calls) will be auto-approved. - If you want to test safely: run the scripts in an isolated VM/container or sandbox, do not point webhook env vars to production endpoints, and do not run master-monitor as a daemon until you verify behavior. - Fix/inspect minor issues: some scripts reference variables that are not set (e.g., lib/approval-respond.sh echoes $NORMALIZED which is never defined) — expect small bugs. Overall: this skill is plausible for its stated goal, but it requires careful review and explicit configuration of webhook tokens and approval modes before use; treat it as untrusted code until you inspect and control its configuration and runtime environment.

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)

clawdbot skill install claude-code-wingman

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

Manual Installation

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

tmux send-keys -t my-session "Run tests"
# ^ Might forget C-m, won't be tracked in dashboard

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:

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

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

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:

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:

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

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <name> \
  --workdir <dir> \
  --prompt "<task>"

Send Command to Existing Session

~/code/claude-code-orchestrator/claude-wingman.sh \
  --session <existing-session> \
  --workdir <same-dir> \
  --prompt "<new command>"

Monitor Session Progress

tmux capture-pane -t <session-name> -p -S -100

List All Active Sessions

tmux ls

Filter for Claude Code sessions:

tmux ls | grep -E "(vsr|clawdbot|proxy|claude)"

View Auto-Approver Log (if needed)

cat /tmp/auto-approver-<session-name>.log

Kill Session When Done

tmux kill-session -t <session-name>

Attach Manually (for user)

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:

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

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

~/code/claude-code-orchestrator/lib/handle-approval.sh approve vsr-bugfix

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

Start the Monitor Daemon

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