Claude Code Supervisor

Supervise Claude Code sessions running in tmux. Uses Claude Code hooks with bash pre-filtering (Option D) and fast LLM triage to detect errors, stuck agents, and task completion. Harness-agnostic — works with OpenClaw, webhooks, ntfy, or any notification backend. Use when: (1) launching long-running Claude Code tasks that need monitoring, (2) setting up automatic nudging for API errors or premature stops, (3) getting progress reports from background coding agents, (4) continuing work after session/context limits reset. Requires: tmux, claude CLI.

Security Scan

The skill appears to implement the claimed tmux/Claude supervision behavior, but there are a few mismatches and sensitive behaviors (sending terminal output to an LLM/notify command, undeclared dependencies, default notify CLI) that you should review before installing.

Purpose & Capability

The name/description match the actual behavior: installing hooks into .claude, reading tmux panes, triaging with a fast LLM, nudging via tmux, and notifying an agent harness. However the metadata omission of commonly used system tools (notably jq and pgrep) is inconsistent with what the scripts require. The default notify command (openclaw gateway call wake --params) and reliance on the claude CLI are reasonable for this skill but are not declared as required tooling/credentials in the metadata.

Instruction Scope

The hook scripts and watchdog capture terminal output and send that context to: (a) the triage LLM (via the configured triage.command) and (b) the configured notify command. That behavior is necessary for supervision but is also sensitive: terminal outputs can contain secrets (keys, tokens, file contents). The scripts will transmit those outputs to whatever triage/notify command you configure (by default the claude CLI and an OpenClaw gateway call). There are no safeguards or redaction steps in the code.

Install Mechanism

There is no external binary download; install-hooks.sh copies provided scripts into the project and merges JSON into .claude/settings.json. This is standard for a hook-based tool. No remote URL downloads or extracted archives are used. The installer does source a local lib.sh and writes a notify wrapper to /tmp.

Credentials

The skill declares only tmux (and optionally claude) as required binaries, but the scripts rely heavily on jq and use pgrep and other system utilities — those are not declared. The default triage command uses the claude CLI (which will use your Claude credentials) and the default notify command uses OpenClaw — both can transmit terminal content. No environment variables or credentials are required explicitly, but the skill will operate using whatever local CLIs/credentials are present (claude, openclaw), which increases the blast radius if misconfigured.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It writes hooks to project .claude/, updates project settings.json, creates a /tmp notify wrapper, and reads/writes a supervisor-state.json in ~/.openclaw/workspace — these are expected for its function and scoped to the project/user. It will run as invoked (hooks or cron) and can act autonomously when events fire, which is normal for a supervisor.

What to consider before installing

This skill mostly does what it says (install hooks, read tmux session output, call a fast LLM to triage, and notify an agent), but review these before installing: - Dependencies: the scripts call jq and pgrep (and expect tmux); metadata only lists tmux and claude. Install jq and ensure required CLIs are present or update the metadata. - Sensitive data: the triage and notify steps send captured terminal output to external commands (by default the claude CLI and an OpenClaw gateway). Terminal output often contains secrets or file contents — ensure the configured triage.command and notify.command target trusted local tools/endpoints, or add redaction before sending. - Default notify: the default notify command calls openclaw gateway; if you don't use OpenClaw, change the notify.command to a safe local script or webhook you control. Inspect the generated /tmp/supervisor-notify.sh and replace it if necessary. - Review hooks: read the hook scripts (on-stop.sh, on-error.sh, on-notify.sh), triage.sh, and lib.sh before installing. They will merge into .claude/settings.json and write files in your project and ~/.openclaw/workspace. - Test in a sandbox: install into a non-sensitive test project first, verify behavior, and confirm notifications/LLM calls don't leak secrets. Consider configuring triage to use a local LLM rather than remote CLAUDE if you have secrecy concerns. If you want me to, I can: (1) list all external binaries/tools the scripts call, (2) suggest a minimal secure configuration (redaction + local notify), or (3) highlight exact lines that send data to external commands.

Bridge between Claude Code's lifecycle hooks and your agent harness.

Architecture

Claude Code (in tmux)
  │  Stop / Error / Notification
  ▼
Bash pre-filter (Option D)
  │  obvious cases handled directly
  │  ambiguous cases pass through
  ▼
Fast LLM triage (claude -p with Haiku, or local LLM)
  │  classifies: FINE | NEEDS_NUDGE | STUCK | DONE | ESCALATE
  │  FINE → logged silently
  ▼
Notify command (configurable)
  │  openclaw wake, webhook, ntfy, script, etc.
  ▼
Agent harness decides + acts
  │  nudge (send-keys to tmux), wait, escalate to human

Quick Start

1. Install hooks into a project

{baseDir}/scripts/install-hooks.sh /path/to/your/project

Creates:

• .claude/hooks/supervisor/ — hook scripts + triage
• .claude/settings.json — wired into Claude Code lifecycle
• .claude-code-supervisor.yml — configuration (edit this)

2. Configure

Edit .claude-code-supervisor.yml:

triage:
  command: "claude -p --no-session-persistence"  # or: ollama run llama3.2
  model: "claude-haiku-4-20250414"

notify:
  command: "openclaw gateway call wake --params"  # or: curl, ntfy, script

3. Register a supervised session

Create ~/.openclaw/workspace/supervisor-state.json (or wherever your harness keeps state):

{
  "sessions": {
    "my-task": {
      "socket": "/tmp/openclaw-tmux-sockets/openclaw.sock",
      "tmuxSession": "my-task",
      "projectDir": "/path/to/project",
      "goal": "Fix issue #42",
      "successCriteria": "Tests pass, committed",
      "maxNudges": 5,
      "escalateAfterMin": 60,
      "status": "running"
    }
  }
}

4. Launch Claude Code in tmux

SOCKET="/tmp/openclaw-tmux-sockets/openclaw.sock"
tmux -S "$SOCKET" new -d -s my-task
tmux -S "$SOCKET" send-keys -t my-task "cd /path/to/project && claude 'Fix issue #42'" Enter

Hooks fire automatically. Triage assesses. You get notified only when it matters.

How the Pre-Filter Works (Option D)

Not every hook event needs an LLM call. Bash catches the obvious cases first:

on-stop.sh

Signal	Bash decision	LLM triage?
max_tokens	Always needs attention	✅ Yes
end_turn + shell prompt back	Agent might be done	✅ Yes
end_turn + no prompt	Agent is mid-work	❌ Skip
stop_sequence	Normal	❌ Skip

on-error.sh

Signal	Bash decision	LLM triage?
API 429 / rate limit	Transient, will resolve	❌ Log only
API 500	Agent likely stuck	✅ Yes
Other tool error	Unknown severity	✅ Yes

on-notify.sh

Signal	Bash decision	LLM triage?
auth_*	Internal, transient	❌ Skip
permission_prompt	Needs decision	✅ Yes
idle_prompt	Agent waiting	✅ Yes

Triage Classifications

The LLM returns one of:

Verdict	Meaning	Typical action
FINE	Agent is working normally	Log silently, no notification
NEEDS_NUDGE	Transient error, should continue	Send "continue" to tmux
STUCK	Looping or not progressing	Try different approach or escalate
DONE	Task completed successfully	Report to human
ESCALATE	Needs human judgment	Notify human with context

Handling Notifications (for agent harness authors)

Wake events arrive with the prefix cc-supervisor: followed by the classification:

cc-supervisor: NEEDS_NUDGE | error:api_500 | cwd=/home/user/project | ...
cc-supervisor: DONE | stopped:end_turn:prompt_back | cwd=/home/user/project | ...

Nudging via tmux

tmux -S "$SOCKET" send-keys -t "$SESSION" "continue — the API error was transient" Enter

Escalation format

See references/escalation-rules.md for when to nudge vs escalate and quiet hours.

Watchdog (Who Watches the Watchman?)

Hooks depend on Claude Code being alive. If the session hard-crashes, hits account limits, or the process gets OOM-killed, no hooks fire. The watchdog catches this.

scripts/watchdog.sh is a pure bash script (no LLM, no Claude Code dependency) that:

1. Reads supervisor-state.json for all "running" sessions
2. Checks: is the tmux socket alive? Is the session there? Is Claude Code still running?
3. If something is dead and no hook reported it → notifies via the configured command
4. Updates lastWatchdogAt in state for tracking

Run it on a timer. Choose your poison:

System cron:

*/15 * * * * /path/to/claude-code-supervisor/scripts/watchdog.sh

OpenClaw cron:

{
  "schedule": { "kind": "every", "everyMs": 900000 },
  "payload": { "kind": "systemEvent", "text": "cc-supervisor: watchdog — run /path/to/scripts/watchdog.sh and report" },
  "sessionTarget": "main"
}

systemd timer, launchd, or whatever runs periodically on your box.

The watchdog is deliberately dumb — no LLM, no complex logic, just "is the process still there?" This means it works even when the triage model is down, the API is melting, or your account hit its limit. Belts and suspenders.

Files

• scripts/install-hooks.sh — one-command setup per project
• scripts/hooks/on-stop.sh — Stop event handler with bash pre-filter
• scripts/hooks/on-error.sh — PostToolUseFailure handler with bash pre-filter
• scripts/hooks/on-notify.sh — Notification handler with bash pre-filter
• scripts/triage.sh — LLM triage (called by hooks for ambiguous cases)
• scripts/lib.sh — shared config loading and notification functions
• scripts/watchdog.sh — dead session detector (pure bash, no LLM dependency)
• references/state-patterns.md — terminal output pattern matching guide
• references/escalation-rules.md — when to nudge vs escalate vs wait
• supervisor.yml.example — example configuration