How do I install the Subagent Overseer skill?

Run npx skillmds@latest add modbender/subagent-overseer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Subagent Overseer safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Subagent Overseer?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Subagent Overseer free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Subagent Overseer?

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Subagent Overseer by modbender — Agent Skill

Name: Subagent Overseer
Rating: 4.5 (4 reviews)
Author: modbender

Subagent Overseer

Monitor sub-agent health and progress via a pull-based bash daemon. Use when spawning sub-agents that need progress tracking, staleness detection, and automatic status reporting. Replaces manual heartbeat polling with a deterministic status file the agent reads every 3 minutes. Zero AI tokens for monitoring — pure OS-level process checks and filesystem diffs.

modbender Updated Sep 9, 2026 12 repo stars

File contents

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.

Quick Start

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

Field	Meaning
`subagents.count`	Active sub-agent sessions
`subagents.details[].stale`	Consecutive cycles with no filesystem changes
`subagents.details[].status`	`active` / `idle` / `warning` / `stuck`
`gateway.health.alive`	Is `openclaw-gateway` running?
`filesystem.changes_since_last`	Files modified since last check

4. Staleness thresholds (at 180s interval)

stale count	Time	Status	Action
0-1	0-3 min	`active`/`idle`	Normal
2-3	6-9 min	`warning`	Voice alert (if --voice)
≥4	≥12 min	`stuck`	Agent 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

Flag	Default	Description
`--interval`	180	Seconds between checks
`--workdir`	cwd	Directory to watch for file changes
`--labels`	(all)	Comma-separated labels to filter
`--max-stale`	4	Cycles before marking `stuck`
`--voice`	off	Local 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)

---name: subagent-overseerdescription: Monitor sub-agent health and progress via a pull-based bash daemon. Use when spawning sub-agents that need progress tracking, staleness detection, and automatic status reporting. Replaces manual heartbeat polling with a deterministic status file the agent reads every 3 minutes. Zero AI tokens for monitoring — pure OS-level process checks and filesystem diffs.--- # 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. ## Quick Start ### 1. Start the overseer when spawning sub-agents ```bash setsid scripts/overseer.sh \ --workdir /path/to/repo \ --interval 180 \ --max-stale 4 \ --voice \ &>/dev/null & ``` ### 2. Heartbeat reads the status file ```bash cat /tmp/overseer/status.json ``` ### 3. Interpret the status | Field | Meaning | |---|---| | `subagents.count` | Active sub-agent sessions | | `subagents.details[].stale` | Consecutive cycles with no filesystem changes | | `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` | | `gateway.health.alive` | Is `openclaw-gateway` running? | | `filesystem.changes_since_last` | Files modified since last check | ### 4. Staleness thresholds (at 180s interval) | stale count | Time | Status | Action | |---|---|---|---| | 0-1 | 0-3 min | `active`/`idle` | Normal | | 2-3 | 6-9 min | `warning` | Voice alert (if --voice) | | ≥4 | ≥12 min | `stuck` | Agent should investigate/kill | ## Heartbeat Handler Protocol When HEARTBEAT.md fires: 1. **Read `/tmp/overseer/status.json`** — if missing or stale (>10 min), restart overseer 2. **If `subagents.count == 0` for 2+ cycles** → overseer auto-exits → reply `HEARTBEAT_OK` 3. **If all agents `active`** → brief one-line status → `HEARTBEAT_OK` 4. **If any `stuck`** → report which labels are stuck → consider killing via `subagents kill` 5. **Never cache a previous heartbeat response.** Always read the status file fresh. ## Flags | Flag | Default | Description | |---|---|---| | `--interval` | 180 | Seconds between checks | | `--workdir` | cwd | Directory to watch for file changes | | `--labels` | (all) | Comma-separated labels to filter | | `--max-stale` | 4 | Cycles before marking `stuck` | | `--voice` | off | Local TTS alerts via `jarvis` command | ## How It Works (No AI Tokens) 1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data. 2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output. 3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir. 4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file. 5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself. 6. **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)

Frequently asked questions