# Send Sub-Agent Overseer to your agent
Use the source page and any available docs to guide the install because the item currently does not return a direct package file.
## Fast path
- Open the source page via Open source listing.
- If you can obtain the package, extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the source page and extracted files.
## Suggested prompts
### New install

```text
I tried to install a skill package from Yavira, but the item currently does not return a direct package file. Inspect the source page and any extracted docs, then tell me what you can confirm and any manual steps still required.
```
### Upgrade existing

```text
I tried to upgrade a skill package from Yavira, but the item currently does not return a direct package file. Compare the source page and any extracted docs with my current installation, then summarize what changed and what manual follow-up I still need.
```
## Machine-readable fields
```json
{
  "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": {
    "downloadUrl": "/downloads/subagent-overseer",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=subagent-overseer",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "scripts/overseer.sh"
    ],
    "downloadMode": "manual_only",
    "sourceHealth": {
      "source": "tencent",
      "slug": "subagent-overseer",
      "status": "source_issue",
      "reason": "not_found",
      "recommendedAction": "review_source",
      "checkedAt": "2026-05-09T13:54:42.067Z",
      "expiresAt": "2026-05-10T13:54:42.067Z",
      "httpStatus": 404,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=subagent-overseer",
      "contentType": "text/plain",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=subagent-overseer",
        "contentDisposition": null,
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "subagent-overseer"
      },
      "scope": "item",
      "summary": "Known item issue.",
      "detail": "This item's current download entry is known to bounce back to a listing or homepage instead of returning a package file.",
      "primaryActionLabel": "Open source listing",
      "primaryActionHref": "https://clawhub.ai/globalcaos/subagent-overseer"
    },
    "validation": {
      "installChecklist": [
        "Open the source listing and confirm there is a real package or setup artifact available.",
        "Review SKILL.md before asking your agent to continue.",
        "Treat this source as manual setup until the upstream download flow is fixed."
      ],
      "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."
      ]
    }
  },
  "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"
  }
}
```
## Documentation

### Sub-Agent Overseer

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.

### Architecture

overseer.sh (bash, runs in background)
    ├── /proc/<pid>  → gateway alive? CPU? threads?
    ├── openclaw sessions list  → sub-agent count + ages
    ├── find -newer marker  → filesystem activity
    └── writes /tmp/overseer/status.json  (atomic mv)

heartbeat (agent, every 3min)
    └── reads /tmp/overseer/status.json → summarize or HEARTBEAT_OK

Key principle: The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.

### 1. Start the overseer when spawning sub-agents

setsid scripts/overseer.sh \\
  --workdir /path/to/repo \\
  --interval 180 \\
  --max-stale 4 \\
  --voice \\
  &>/dev/null &

### 2. Heartbeat reads the status file

cat /tmp/overseer/status.json

### 3. Interpret the status

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

### 4. Staleness thresholds (at 180s interval)

stale countTimeStatusAction0-10-3 minactive/idleNormal2-36-9 minwarningVoice alert (if --voice)≥4≥12 minstuckAgent should investigate/kill

### Heartbeat Handler Protocol

When HEARTBEAT.md fires:

Read /tmp/overseer/status.json — if missing or stale (>10 min), restart overseer
If subagents.count == 0 for 2+ cycles → overseer auto-exits → reply HEARTBEAT_OK
If all agents active → brief one-line status → HEARTBEAT_OK
If any stuck → report which labels are stuck → consider killing via subagents kill
Never cache a previous heartbeat response. Always read the status file fresh.

### Flags

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

### How It Works (No AI Tokens)

Gateway health: Reads /proc/<pid>/status for CPU, memory, threads, FD count. Pure kernel data.
Sub-agent list: Single openclaw sessions list call per cycle. Parses grep output.
Filesystem diff: find -newer marker — detects any file writes in the workdir.
Status file: JSON written atomically (write to temp, mv into place). Any reader sees a complete file.
Self-exit: If no sub-agents for 2 consecutive cycles, the overseer stops itself.
Dedup: flock ensures only one overseer instance runs at a time.

### Cost

Overseer: $0.00 (bash + /proc + one CLI call per cycle)
Voice alerts: $0.00 (local sherpa-onnx via jarvis)
Heartbeat reads status file: $0.00 (one cat command)
Only cost is the heartbeat model itself (qwen3 local = free)

### Pairs Well With

agent-superpowers — the three-agent review pipeline that Overseer was built to monitor
smart-model-router — auto-select models for each sub-agent role

👉 https://github.com/globalcaos/tinkerclaw

Clone it. Fork it. Break it. Make it yours.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: globalcaos
- Version: 1.1.0
## Source health
- Status: source_issue
- Known item issue.
- This item's current download entry is known to bounce back to a listing or homepage instead of returning a package file.
- Health scope: item
- Reason: not_found
- Checked at: 2026-05-09T13:54:42.067Z
- Expires at: 2026-05-10T13:54:42.067Z
- Recommended action: Open source listing
## Links
- [Detail page](https://openagent3.xyz/skills/subagent-overseer)
- [Send to Agent page](https://openagent3.xyz/skills/subagent-overseer/agent)
- [JSON manifest](https://openagent3.xyz/skills/subagent-overseer/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/subagent-overseer/agent.md)
- [Download page](https://openagent3.xyz/downloads/subagent-overseer)