{
  "schemaVersion": "1.0",
  "item": {
    "slug": "subagent-overseer",
    "name": "Sub-Agent Overseer",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/globalcaos/subagent-overseer",
    "canonicalUrl": "https://clawhub.ai/globalcaos/subagent-overseer",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/subagent-overseer",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=subagent-overseer",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "scripts/overseer.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. 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. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/subagent-overseer"
    },
    "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/subagent-overseer",
    "agentPageUrl": "https://openagent3.xyz/skills/subagent-overseer/agent",
    "manifestUrl": "https://openagent3.xyz/skills/subagent-overseer/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/subagent-overseer/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. 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. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Sub-Agent Overseer",
        "body": "Lightweight pull-based daemon that monitors sub-agent health. Writes a status file every N seconds. The heartbeat handler reads it — no push, no noise."
      },
      {
        "title": "Architecture",
        "body": "overseer.sh (bash, runs in background)\n    ├── /proc/<pid>  → gateway alive? CPU? threads?\n    ├── openclaw sessions list  → sub-agent count + ages\n    ├── find -newer marker  → filesystem activity\n    └── writes /tmp/overseer/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads /tmp/overseer/status.json → summarize or HEARTBEAT_OK\n\nKey principle: The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy."
      },
      {
        "title": "1. Start the overseer when spawning sub-agents",
        "body": "setsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  --voice \\\n  &>/dev/null &"
      },
      {
        "title": "2. Heartbeat reads the status file",
        "body": "cat /tmp/overseer/status.json"
      },
      {
        "title": "3. Interpret the status",
        "body": "FieldMeaningsubagents.countActive sub-agent sessionssubagents.details[].staleConsecutive cycles with no filesystem changessubagents.details[].statusactive / idle / warning / stuckgateway.health.aliveIs openclaw-gateway running?filesystem.changes_since_lastFiles modified since last check"
      },
      {
        "title": "4. Staleness thresholds (at 180s interval)",
        "body": "stale countTimeStatusAction0-10-3 minactive/idleNormal2-36-9 minwarningVoice alert (if --voice)≥4≥12 minstuckAgent should investigate/kill"
      },
      {
        "title": "Heartbeat Handler Protocol",
        "body": "When HEARTBEAT.md fires:\n\nRead /tmp/overseer/status.json — if missing or stale (>10 min), restart overseer\nIf subagents.count == 0 for 2+ cycles → overseer auto-exits → reply HEARTBEAT_OK\nIf all agents active → brief one-line status → HEARTBEAT_OK\nIf any stuck → report which labels are stuck → consider killing via subagents kill\nNever cache a previous heartbeat response. Always read the status file fresh."
      },
      {
        "title": "Flags",
        "body": "FlagDefaultDescription--interval180Seconds between checks--workdircwdDirectory to watch for file changes--labels(all)Comma-separated labels to filter--max-stale4Cycles before marking stuck--voiceoffLocal TTS alerts via jarvis command"
      },
      {
        "title": "How It Works (No AI Tokens)",
        "body": "Gateway health: Reads /proc/<pid>/status for CPU, memory, threads, FD count. Pure kernel data.\nSub-agent list: Single openclaw sessions list call per cycle. Parses grep output.\nFilesystem diff: find -newer marker — detects any file writes in the workdir.\nStatus file: JSON written atomically (write to temp, mv into place). Any reader sees a complete file.\nSelf-exit: If no sub-agents for 2 consecutive cycles, the overseer stops itself.\nDedup: flock ensures only one overseer instance runs at a time."
      },
      {
        "title": "Cost",
        "body": "Overseer: $0.00 (bash + /proc + one CLI call per cycle)\nVoice alerts: $0.00 (local sherpa-onnx via jarvis)\nHeartbeat reads status file: $0.00 (one cat command)\nOnly cost is the heartbeat model itself (qwen3 local = free)"
      },
      {
        "title": "Pairs Well With",
        "body": "agent-superpowers — the three-agent review pipeline that Overseer was built to monitor\nsmart-model-router — auto-select models for each sub-agent role\n\n👉 https://github.com/globalcaos/tinkerclaw\n\nClone it. Fork it. Break it. Make it yours."
      }
    ],
    "body": "Sub-Agent Overseer\n\nLightweight pull-based daemon that monitors sub-agent health. Writes a status file every N seconds. The heartbeat handler reads it — no push, no noise.\n\nArchitecture\noverseer.sh (bash, runs in background)\n    ├── /proc/<pid>  → gateway alive? CPU? threads?\n    ├── openclaw sessions list  → sub-agent count + ages\n    ├── find -newer marker  → filesystem activity\n    └── writes /tmp/overseer/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads /tmp/overseer/status.json → summarize or HEARTBEAT_OK\n\n\nKey principle: The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\nQuick Start\n1. Start the overseer when spawning sub-agents\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  --voice \\\n  &>/dev/null &\n\n2. Heartbeat reads the status file\ncat /tmp/overseer/status.json\n\n3. Interpret the status\nField\tMeaning\nsubagents.count\tActive sub-agent sessions\nsubagents.details[].stale\tConsecutive cycles with no filesystem changes\nsubagents.details[].status\tactive / idle / warning / stuck\ngateway.health.alive\tIs openclaw-gateway running?\nfilesystem.changes_since_last\tFiles modified since last check\n4. Staleness thresholds (at 180s interval)\nstale count\tTime\tStatus\tAction\n0-1\t0-3 min\tactive/idle\tNormal\n2-3\t6-9 min\twarning\tVoice alert (if --voice)\n≥4\t≥12 min\tstuck\tAgent should investigate/kill\nHeartbeat Handler Protocol\n\nWhen HEARTBEAT.md fires:\n\nRead /tmp/overseer/status.json — if missing or stale (>10 min), restart overseer\nIf subagents.count == 0 for 2+ cycles → overseer auto-exits → reply HEARTBEAT_OK\nIf all agents active → brief one-line status → HEARTBEAT_OK\nIf any stuck → report which labels are stuck → consider killing via subagents kill\nNever cache a previous heartbeat response. Always read the status file fresh.\nFlags\nFlag\tDefault\tDescription\n--interval\t180\tSeconds between checks\n--workdir\tcwd\tDirectory to watch for file changes\n--labels\t(all)\tComma-separated labels to filter\n--max-stale\t4\tCycles before marking stuck\n--voice\toff\tLocal TTS alerts via jarvis command\nHow It Works (No AI Tokens)\nGateway health: Reads /proc/<pid>/status for CPU, memory, threads, FD count. Pure kernel data.\nSub-agent list: Single openclaw sessions list call per cycle. Parses grep output.\nFilesystem diff: find -newer marker — detects any file writes in the workdir.\nStatus file: JSON written atomically (write to temp, mv into place). Any reader sees a complete file.\nSelf-exit: If no sub-agents for 2 consecutive cycles, the overseer stops itself.\nDedup: flock ensures only one overseer instance runs at a time.\nCost\nOverseer: $0.00 (bash + /proc + one CLI call per cycle)\nVoice alerts: $0.00 (local sherpa-onnx via jarvis)\nHeartbeat reads status file: $0.00 (one cat command)\nOnly cost is the heartbeat model itself (qwen3 local = free)\nPairs Well With\nagent-superpowers — the three-agent review pipeline that Overseer was built to monitor\nsmart-model-router — auto-select models for each sub-agent role\n\n👉 https://github.com/globalcaos/tinkerclaw\n\nClone it. Fork it. Break it. Make it yours."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/globalcaos/subagent-overseer",
    "publisherUrl": "https://clawhub.ai/globalcaos/subagent-overseer",
    "owner": "globalcaos",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/subagent-overseer",
    "downloadUrl": "https://openagent3.xyz/downloads/subagent-overseer",
    "agentUrl": "https://openagent3.xyz/skills/subagent-overseer/agent",
    "manifestUrl": "https://openagent3.xyz/skills/subagent-overseer/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/subagent-overseer/agent.md"
  }
}