A robust supervision layer for Claude Code that monitors tmux sessions, triages errors with LLM intelligence, and automates agent recovery.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install claude-code-supervisor
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install claude-code-supervisor using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Claude Code Supervisor?
The Claude Code Supervisor acts as a sophisticated bridge between the Claude Code lifecycle hooks and your existing agent harness, specifically designed to manage long-running background development tasks. By leveraging Openclaw Skills, this tool monitors tmux-based sessions to detect when an agent is stuck, has encountered a transient error, or has successfully reached its goal.
The system utilizes a hybrid architecture featuring a bash pre-filter for high-speed evaluation of common events and a fast LLM triage layer for complex decision-making. This ensures that the supervisor only escalates issues to a human developer when necessary, while automatically handling routine tasks like API rate-limit pauses or session nudges.
Claude Code Supervisor Use Cases
- Launching long-running Claude Code tasks that require continuous monitoring without active terminal focus.
- Setting up automatic recovery nudges for transient API 500 errors or premature session stops.
- Generating consolidated progress reports from multiple background coding agents via centralized notifications.
- Resuming complex workflows automatically after context limits or session resets occur.
How Claude Code Supervisor Works
- Claude Code is launched within a tmux session, where it triggers integrated lifecycle hooks during stop, error, or notification events.
- A bash pre-filter immediately evaluates the signal to handle obvious cases like rate limits or known stop sequences without incurring LLM costs.
- Ambiguous scenarios are passed to a high-speed LLM triage (such as Claude Haiku) to classify the agent's state into categories like NEEDS_NUDGE, STUCK, or DONE.
- The system triggers a notification through the Openclaw Skills gateway or other configured backends like webhooks or ntfy based on the triage verdict.
- The agent harness or user performs the corrective action, such as sending a 'continue' command back to the tmux session to resume work.
Claude Code Supervisor Setup
To get started, install the supervisor hooks into your project directory using the installation script:
./scripts/install-hooks.sh /path/to/your/project
Configure your triage model and notification command in the .claude-code-supervisor.yml file:
triage:
command: "claude -p --no-session-persistence"
model: "claude-haiku-4-20250414"
notify:
command: "openclaw gateway call wake --params"
Finally, register your supervised session in your workspace state file to enable tracking and the automated watchdog service.
Claude Code Supervisor Data Schema & Taxonomy
The skill organizes its operation through a set of configuration and state files that track session health:
| File / Key | Purpose |
|---|---|
.claude/hooks/supervisor/ |
Stores the bash scripts for event handling and LLM triage logic. |
.claude-code-supervisor.yml |
Defines the triage model and notification backend settings. |
supervisor-state.json |
Maintains metadata for running sessions, including tmux socket paths, project directories, and success criteria. |
lastWatchdogAt |
A timestamp used by the watchdog to ensure the monitoring process is active. |
maxNudges |
A configuration value that limits how many times the supervisor will automatically restart a stuck agent. |
Claude Code Supervisor Advanced Features
- Intelligent Watchdog: A pure bash script that detects hard crashes or OOM-killed sessions even if the LLM triage service is unavailable.
- Openclaw Skills Integration: Native support for waking agent harnesses and triggering automated recovery workflows via the Openclaw gateway.
- Multi-Session Management: Concurrently monitor and triage multiple Claude Code instances across different project directories and tmux sockets.
- Configurable Triage Verdicts: Custom logic to decide between automatic recovery, silent logging, or immediate human escalation based on project-specific rules.
SKILL.md
Loading
Related Openclaw Skills
Shitty Email
A streamlined tool for generating and managing temporary, disposable email addresses for automated workflows and privacy.
PayAHuman
A specialized skill for Openclaw agents to programmatically compensate humans via email or social media handles using Talentir.
Avatar
A high-fidelity interactive AI avatar interface featuring real-time lip-syncing and high-quality text-to-speech.
Vision Sandbox
Vision Sandbox leverages Gemini's native code execution to provide high-precision spatial grounding, visual math, and automated UI auditing.
Privacy Cards
A powerful programmatic interface for creating and managing Privacy.com virtual payment cards through Openclaw Skills.
Polymarket FastLoop Trader
An automated trading agent that executes short-term Polymarket trades based on real-time CEX price momentum.
Featured*
