{
  "schemaVersion": "1.0",
  "item": {
    "slug": "claude-code-supervisor",
    "name": "Claude Code Supervisor",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/johba37/claude-code-supervisor",
    "canonicalUrl": "https://clawhub.ai/johba37/claude-code-supervisor",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/claude-code-supervisor",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-supervisor",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "assets/supervisor-state.template.json",
      "references/escalation-rules.md",
      "references/state-patterns.md",
      "scripts/hooks/on-error.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "claude-code-supervisor",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-01T11:29:37.971Z",
      "expiresAt": "2026-05-08T11:29:37.971Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-supervisor",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claude-code-supervisor",
        "contentDisposition": "attachment; filename=\"claude-code-supervisor-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "claude-code-supervisor"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/claude-code-supervisor"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/claude-code-supervisor",
    "agentPageUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent",
    "manifestUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Claude Code Supervisor",
        "body": "Bridge between Claude Code's lifecycle hooks and your agent harness."
      },
      {
        "title": "Architecture",
        "body": "Claude Code (in tmux)\n  │  Stop / Error / Notification\n  ▼\nBash pre-filter (Option D)\n  │  obvious cases handled directly\n  │  ambiguous cases pass through\n  ▼\nFast LLM triage (claude -p with Haiku, or local LLM)\n  │  classifies: FINE | NEEDS_NUDGE | STUCK | DONE | ESCALATE\n  │  FINE → logged silently\n  ▼\nNotify command (configurable)\n  │  openclaw wake, webhook, ntfy, script, etc.\n  ▼\nAgent harness decides + acts\n  │  nudge (send-keys to tmux), wait, escalate to human"
      },
      {
        "title": "1. Install hooks into a project",
        "body": "{baseDir}/scripts/install-hooks.sh /path/to/your/project\n\nCreates:\n\n.claude/hooks/supervisor/ — hook scripts + triage\n.claude/settings.json — wired into Claude Code lifecycle\n.claude-code-supervisor.yml — configuration (edit this)"
      },
      {
        "title": "2. Configure",
        "body": "Edit .claude-code-supervisor.yml:\n\ntriage:\n  command: \"claude -p --no-session-persistence\"  # or: ollama run llama3.2\n  model: \"claude-haiku-4-20250414\"\n\nnotify:\n  command: \"openclaw gateway call wake --params\"  # or: curl, ntfy, script"
      },
      {
        "title": "3. Register a supervised session",
        "body": "Create ~/.openclaw/workspace/supervisor-state.json (or wherever your harness keeps state):\n\n{\n  \"sessions\": {\n    \"my-task\": {\n      \"socket\": \"/tmp/openclaw-tmux-sockets/openclaw.sock\",\n      \"tmuxSession\": \"my-task\",\n      \"projectDir\": \"/path/to/project\",\n      \"goal\": \"Fix issue #42\",\n      \"successCriteria\": \"Tests pass, committed\",\n      \"maxNudges\": 5,\n      \"escalateAfterMin\": 60,\n      \"status\": \"running\"\n    }\n  }\n}"
      },
      {
        "title": "4. Launch Claude Code in tmux",
        "body": "SOCKET=\"/tmp/openclaw-tmux-sockets/openclaw.sock\"\ntmux -S \"$SOCKET\" new -d -s my-task\ntmux -S \"$SOCKET\" send-keys -t my-task \"cd /path/to/project && claude 'Fix issue #42'\" Enter\n\nHooks fire automatically. Triage assesses. You get notified only when it matters."
      },
      {
        "title": "How the Pre-Filter Works (Option D)",
        "body": "Not every hook event needs an LLM call. Bash catches the obvious cases first:"
      },
      {
        "title": "on-stop.sh",
        "body": "SignalBash decisionLLM triage?max_tokensAlways needs attention✅ Yesend_turn + shell prompt backAgent might be done✅ Yesend_turn + no promptAgent is mid-work❌ Skipstop_sequenceNormal❌ Skip"
      },
      {
        "title": "on-error.sh",
        "body": "SignalBash decisionLLM triage?API 429 / rate limitTransient, will resolve❌ Log onlyAPI 500Agent likely stuck✅ YesOther tool errorUnknown severity✅ Yes"
      },
      {
        "title": "on-notify.sh",
        "body": "SignalBash decisionLLM triage?auth_*Internal, transient❌ Skippermission_promptNeeds decision✅ Yesidle_promptAgent waiting✅ Yes"
      },
      {
        "title": "Triage Classifications",
        "body": "The LLM returns one of:\n\nVerdictMeaningTypical actionFINEAgent is working normallyLog silently, no notificationNEEDS_NUDGETransient error, should continueSend \"continue\" to tmuxSTUCKLooping or not progressingTry different approach or escalateDONETask completed successfullyReport to humanESCALATENeeds human judgmentNotify human with context"
      },
      {
        "title": "Handling Notifications (for agent harness authors)",
        "body": "Wake events arrive with the prefix cc-supervisor: followed by the classification:\n\ncc-supervisor: NEEDS_NUDGE | error:api_500 | cwd=/home/user/project | ...\ncc-supervisor: DONE | stopped:end_turn:prompt_back | cwd=/home/user/project | ..."
      },
      {
        "title": "Nudging via tmux",
        "body": "tmux -S \"$SOCKET\" send-keys -t \"$SESSION\" \"continue — the API error was transient\" Enter"
      },
      {
        "title": "Escalation format",
        "body": "See references/escalation-rules.md for when to nudge vs escalate and quiet hours."
      },
      {
        "title": "Watchdog (Who Watches the Watchman?)",
        "body": "Hooks depend on Claude Code being alive. If the session hard-crashes, hits account\nlimits, or the process gets OOM-killed, no hooks fire. The watchdog catches this.\n\nscripts/watchdog.sh is a pure bash script (no LLM, no Claude Code dependency) that:\n\nReads supervisor-state.json for all \"running\" sessions\nChecks: is the tmux socket alive? Is the session there? Is Claude Code still running?\nIf something is dead and no hook reported it → notifies via the configured command\nUpdates lastWatchdogAt in state for tracking\n\nRun it on a timer. Choose your poison:\n\nSystem cron:\n\n*/15 * * * * /path/to/claude-code-supervisor/scripts/watchdog.sh\n\nOpenClaw cron:\n\n{\n  \"schedule\": { \"kind\": \"every\", \"everyMs\": 900000 },\n  \"payload\": { \"kind\": \"systemEvent\", \"text\": \"cc-supervisor: watchdog — run /path/to/scripts/watchdog.sh and report\" },\n  \"sessionTarget\": \"main\"\n}\n\nsystemd timer, launchd, or whatever runs periodically on your box.\n\nThe watchdog is deliberately dumb — no LLM, no complex logic, just \"is the process still\nthere?\" This means it works even when the triage model is down, the API is melting, or\nyour account hit its limit. Belts and suspenders."
      },
      {
        "title": "Files",
        "body": "scripts/install-hooks.sh — one-command setup per project\nscripts/hooks/on-stop.sh — Stop event handler with bash pre-filter\nscripts/hooks/on-error.sh — PostToolUseFailure handler with bash pre-filter\nscripts/hooks/on-notify.sh — Notification handler with bash pre-filter\nscripts/triage.sh — LLM triage (called by hooks for ambiguous cases)\nscripts/lib.sh — shared config loading and notification functions\nscripts/watchdog.sh — dead session detector (pure bash, no LLM dependency)\nreferences/state-patterns.md — terminal output pattern matching guide\nreferences/escalation-rules.md — when to nudge vs escalate vs wait\nsupervisor.yml.example — example configuration"
      }
    ],
    "body": "Claude Code Supervisor\n\nBridge between Claude Code's lifecycle hooks and your agent harness.\n\nArchitecture\nClaude Code (in tmux)\n  │  Stop / Error / Notification\n  ▼\nBash pre-filter (Option D)\n  │  obvious cases handled directly\n  │  ambiguous cases pass through\n  ▼\nFast LLM triage (claude -p with Haiku, or local LLM)\n  │  classifies: FINE | NEEDS_NUDGE | STUCK | DONE | ESCALATE\n  │  FINE → logged silently\n  ▼\nNotify command (configurable)\n  │  openclaw wake, webhook, ntfy, script, etc.\n  ▼\nAgent harness decides + acts\n  │  nudge (send-keys to tmux), wait, escalate to human\n\nQuick Start\n1. Install hooks into a project\n{baseDir}/scripts/install-hooks.sh /path/to/your/project\n\n\nCreates:\n\n.claude/hooks/supervisor/ — hook scripts + triage\n.claude/settings.json — wired into Claude Code lifecycle\n.claude-code-supervisor.yml — configuration (edit this)\n2. Configure\n\nEdit .claude-code-supervisor.yml:\n\ntriage:\n  command: \"claude -p --no-session-persistence\"  # or: ollama run llama3.2\n  model: \"claude-haiku-4-20250414\"\n\nnotify:\n  command: \"openclaw gateway call wake --params\"  # or: curl, ntfy, script\n\n3. Register a supervised session\n\nCreate ~/.openclaw/workspace/supervisor-state.json (or wherever your harness keeps state):\n\n{\n  \"sessions\": {\n    \"my-task\": {\n      \"socket\": \"/tmp/openclaw-tmux-sockets/openclaw.sock\",\n      \"tmuxSession\": \"my-task\",\n      \"projectDir\": \"/path/to/project\",\n      \"goal\": \"Fix issue #42\",\n      \"successCriteria\": \"Tests pass, committed\",\n      \"maxNudges\": 5,\n      \"escalateAfterMin\": 60,\n      \"status\": \"running\"\n    }\n  }\n}\n\n4. Launch Claude Code in tmux\nSOCKET=\"/tmp/openclaw-tmux-sockets/openclaw.sock\"\ntmux -S \"$SOCKET\" new -d -s my-task\ntmux -S \"$SOCKET\" send-keys -t my-task \"cd /path/to/project && claude 'Fix issue #42'\" Enter\n\n\nHooks fire automatically. Triage assesses. You get notified only when it matters.\n\nHow the Pre-Filter Works (Option D)\n\nNot every hook event needs an LLM call. Bash catches the obvious cases first:\n\non-stop.sh\nSignal\tBash decision\tLLM triage?\nmax_tokens\tAlways needs attention\t✅ Yes\nend_turn + shell prompt back\tAgent might be done\t✅ Yes\nend_turn + no prompt\tAgent is mid-work\t❌ Skip\nstop_sequence\tNormal\t❌ Skip\non-error.sh\nSignal\tBash decision\tLLM triage?\nAPI 429 / rate limit\tTransient, will resolve\t❌ Log only\nAPI 500\tAgent likely stuck\t✅ Yes\nOther tool error\tUnknown severity\t✅ Yes\non-notify.sh\nSignal\tBash decision\tLLM triage?\nauth_*\tInternal, transient\t❌ Skip\npermission_prompt\tNeeds decision\t✅ Yes\nidle_prompt\tAgent waiting\t✅ Yes\nTriage Classifications\n\nThe LLM returns one of:\n\nVerdict\tMeaning\tTypical action\nFINE\tAgent is working normally\tLog silently, no notification\nNEEDS_NUDGE\tTransient error, should continue\tSend \"continue\" to tmux\nSTUCK\tLooping or not progressing\tTry different approach or escalate\nDONE\tTask completed successfully\tReport to human\nESCALATE\tNeeds human judgment\tNotify human with context\nHandling Notifications (for agent harness authors)\n\nWake events arrive with the prefix cc-supervisor: followed by the classification:\n\ncc-supervisor: NEEDS_NUDGE | error:api_500 | cwd=/home/user/project | ...\ncc-supervisor: DONE | stopped:end_turn:prompt_back | cwd=/home/user/project | ...\n\nNudging via tmux\ntmux -S \"$SOCKET\" send-keys -t \"$SESSION\" \"continue — the API error was transient\" Enter\n\nEscalation format\n\nSee references/escalation-rules.md for when to nudge vs escalate and quiet hours.\n\nWatchdog (Who Watches the Watchman?)\n\nHooks 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.\n\nscripts/watchdog.sh is a pure bash script (no LLM, no Claude Code dependency) that:\n\nReads supervisor-state.json for all \"running\" sessions\nChecks: is the tmux socket alive? Is the session there? Is Claude Code still running?\nIf something is dead and no hook reported it → notifies via the configured command\nUpdates lastWatchdogAt in state for tracking\n\nRun it on a timer. Choose your poison:\n\nSystem cron:\n\n*/15 * * * * /path/to/claude-code-supervisor/scripts/watchdog.sh\n\n\nOpenClaw cron:\n\n{\n  \"schedule\": { \"kind\": \"every\", \"everyMs\": 900000 },\n  \"payload\": { \"kind\": \"systemEvent\", \"text\": \"cc-supervisor: watchdog — run /path/to/scripts/watchdog.sh and report\" },\n  \"sessionTarget\": \"main\"\n}\n\n\nsystemd timer, launchd, or whatever runs periodically on your box.\n\nThe 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.\n\nFiles\nscripts/install-hooks.sh — one-command setup per project\nscripts/hooks/on-stop.sh — Stop event handler with bash pre-filter\nscripts/hooks/on-error.sh — PostToolUseFailure handler with bash pre-filter\nscripts/hooks/on-notify.sh — Notification handler with bash pre-filter\nscripts/triage.sh — LLM triage (called by hooks for ambiguous cases)\nscripts/lib.sh — shared config loading and notification functions\nscripts/watchdog.sh — dead session detector (pure bash, no LLM dependency)\nreferences/state-patterns.md — terminal output pattern matching guide\nreferences/escalation-rules.md — when to nudge vs escalate vs wait\nsupervisor.yml.example — example configuration"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/johba37/claude-code-supervisor",
    "publisherUrl": "https://clawhub.ai/johba37/claude-code-supervisor",
    "owner": "johba37",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/claude-code-supervisor",
    "downloadUrl": "https://openagent3.xyz/downloads/claude-code-supervisor",
    "agentUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent",
    "manifestUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/claude-code-supervisor/agent.md"
  }
}