claude-code-supervisor

What This Skill Does

The claude-code-supervisor skill acts as an intelligent bridge between the Claude Code CLI and your local OpenClaw agent harness. By hooking into the Claude Code lifecycle, this skill monitors background sessions running in tmux. It employs a two-tier verification system: a bash-based pre-filter (Option D) that discards routine noise and an LLM-powered triage step (using lightweight models like Haiku) to evaluate the health of the coding agent. It detects when agents are stuck, require human intervention for permissions, or have finished a task, notifying your preferred output channel—whether that be an OpenClaw notification, ntfy, or a custom webhook. This effectively automates the management of autonomous coding sessions.

Installation

To begin, ensure you have tmux and the Claude CLI installed on your machine. You can install this skill by running: clawhub install openclaw/skills/skills/johba37/claude-code-supervisor inside your terminal. After installation, execute the script at {baseDir}/scripts/install-hooks.sh /path/to/your/project to wire the supervisor into your project directory. This generates the necessary .claude/ configuration files. Configure your notification preferences and LLM endpoint in the generated .claude-code-supervisor.yml file, and ensure your session state is registered in ~/.openclaw/workspace/supervisor-state.json to enable active tracking.

Use Cases

1. Automated Long-Running Tasks: Perfect for large refactoring jobs or comprehensive test suites that exceed standard timeout limits.
2. Proactive Nudging: Automatically triggers a nudge (via tmux send-keys) if the agent hangs on a 500 error or requires a specific user interaction that was previously missed.
3. Progress Reporting: Receive concise updates from long-running background tasks without needing to monitor the terminal buffer manually.
4. Failure Recovery: Automatically detect when an agent hit a token limit or rate limit and reset or pause the session state accordingly.

Example Prompts

1. "OpenClaw, launch a new claude-code-supervisor session for the user authentication refactor in the backend repo."
2. "Check the status of my active tmux coding sessions and notify me if any have stalled or require a nudge."
3. "Configure the supervisor to escalate to me on Slack if the 'data-migration' session hits a blocking error after three retries."

Tips & Limitations

• Efficiency: Use the fastest available LLM for triage (e.g., Haiku) to minimize latency and costs. The bash pre-filter is your primary defense against unnecessary API calls—customize it to fit your specific workflow.
• Security: The supervisor can perform send-keys to your terminal sessions. Ensure you restrict access to the tmux socket files.
• Limitations: This skill relies on the stability of the Claude Code CLI and tmux. If the underlying tmux server crashes, the supervisor will lose the connection to the session.