{"id":"ce0cee4e-ac88-4329-a825-8a251a7bd96b","entityType":"agent","slug":"clawhub-globalcaos-subagent-overseer","name":"TinkerClaw Subagent Overseer","canonicalUrl":"https://www.xpersona.co/agent/clawhub-globalcaos-subagent-overseer","canonicalPath":"/agent/clawhub-globalcaos-subagent-overseer","generatedAt":"2026-10-10T21:43:11.330Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":null},"description":"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats. Skill: TinkerClaw Subagent Overseer Owner: globalcaos Summary: You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats. Tags: latest:1.1.3 Version history: v1.1.3 | 2026-09-17T12:05:38.026Z | user --stop now signals only when all of these hold: the pid is a number, the flock","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17324vfeqe0ptzp84z2z9vttx883zdg:subagent-overseer","sourceUrl":"https://clawhub.ai/globalcaos/subagent-overseer","homepage":"https://clawhub.ai/globalcaos/skills/subagent-overseer","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/globalcaos/subagent-overseer","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/globalcaos/skills/subagent-overseer","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":null},"stars":null,"forks":null,"downloads":1357,"packageName":null,"latestVersion":"1.1.3","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T15:36:42.239Z","lastCrawledAt":"2026-10-10T15:36:42.239Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T15:36:42.239Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.3","createdAt":"2026-09-17T12:05:38.026Z","changelog":"--stop now signals only when all of these hold: the pid is a number, the flock lock is held, the process belon; A missing directory is created with umask 077; The sleep now runs in the background and the loop waits on it, so the TERM trap fires at once; --cleanup now exits 1 and leaves the state in place if the stop fails; list_subagents now filters by the comma-separated label list; Both flags must now be positive integers; SKILL; The row now reads 'Report to user; kill only","fileCount":5,"zipByteSize":15968},{"version":"1.1.2","createdAt":"2026-09-09T08:51:02.435Z","changelog":"Stop/cleanup path and privacy warning for voice/filename leakage.","fileCount":5,"zipByteSize":13162},{"version":"1.1.1","createdAt":"2026-06-06T16:50:42.927Z","changelog":"TinkerClaw rebrand + funnel to github.com/globalcaos/tinkerclaw","fileCount":3,"zipByteSize":5481},{"version":"1.1.0","createdAt":"2026-03-10T15:39:49.071Z","changelog":"Marketia-grade description, conversion block, skill pairings","fileCount":3,"zipByteSize":5481},{"version":"1.0.0","createdAt":"2026-02-21T18:27:59.094Z","changelog":"Initial release: pull-based sub-agent monitor daemon with /proc health checks, filesystem diffs, atomic status file, and optional local voice alerts","fileCount":3,"zipByteSize":5249}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17324vfeqe0ptzp84z2z9vttx883zdg:subagent-overseer","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:43:11.329Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-globalcaos-subagent-overseer/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":null},"readme":"Skill: TinkerClaw Subagent Overseer\n\nOwner: globalcaos\n\nSummary: You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\n\nTags: latest:1.1.3\n\nVersion history:\n\nv1.1.3 | 2026-09-17T12:05:38.026Z | user\n\n--stop now signals only when all of these hold: the pid is a number, the flock lock is held, the process belon; A missing directory is created with umask 077; The sleep now runs in the background and the loop waits on it, so the TERM trap fires at once; --cleanup now exits 1 and leaves the state in place if the stop fails; list_subagents now filters by the comma-separated label list; Both flags must now be positive integers; SKILL; The row now reads 'Report to user; kill only\n\nv1.1.2 | 2026-09-09T08:51:02.435Z | user\n\nStop/cleanup path and privacy warning for voice/filename leakage.\n\nv1.1.1 | 2026-06-06T16:50:42.927Z | user\n\nTinkerClaw rebrand + funnel to github.com/globalcaos/tinkerclaw\n\nv1.1.0 | 2026-03-10T15:39:49.071Z | user\n\nMarketia-grade description, conversion block, skill pairings\n\nv1.0.0 | 2026-02-21T18:27:59.094Z | user\n\nInitial release: pull-based sub-agent monitor daemon with /proc health checks, filesystem diffs, atomic status file, and optional local voice alerts\n\nArchive index:\n\nArchive v1.1.3: 5 files, 15968 bytes\n\nFiles: scripts/overseer.sh (20062b), skill-card.md (2257b), SKILL.md (10438b), tests/test_overseer.sh (8480b), _meta.json (136b)\n\nFile v1.1.3:SKILL.md\n\n---\nname: subagent-overseer\nversion: 1.1.3\ndescription: \"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\"\nmetadata:\n  openclaw:\n    emoji: \"👁️\"\n    notes:\n      security: \"No network calls, no credentials, no writes outside its own status directory. It reads /proc, runs `openclaw sessions list` once per cycle, and counts recently-changed files under --workdir. The one piece of real content it handles is filenames: the status file records the basenames of up to five recently-changed files, which can reveal what you are working on. That directory is per-user and mode 0700 (XDG_RUNTIME_DIR, else /tmp/overseer-$UID); an existing directory that is a symlink, owned by someone else, or group/other-accessible is refused rather than used. --no-filenames drops the names entirely; voice alerts speak counts only unless you pass --voice-files. It is a background daemon with its own off switch: --stop signals the recorded pid only if the lock is held and that pid is your own overseer.sh process, so a stale or planted pid file cannot make it kill anything else.\"\n---\n\n# Sub-Agent Overseer\n\n> One of dozens of skills and plugins in **[TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — a self-improving OpenClaw fork that's been running 24/7 for months.\n\nYou spawned 4 sub-agents. One died 20 minutes ago. You're still waiting.\n\nNobody told you, because nobody was watching — and the thing you'd normally ask to watch them charges you a tool call every time it blinks.\n\nThere's a cheaper kind of eye for this.\n\nOverseer keeps watch over your sub-agents the way the operating system already does — checking which ones are still running and how long each has gone quiet. A tiny background process writes down their health every few minutes (every 180 s by default, set with `--interval`), so when your agent's heartbeat wakes up, it just reads that note and goes back to sleep. While everything is healthy it spends nothing: no model, no questions, no busywork. The moment an agent stalls or dies, the note says so, and you can act before another twenty minutes leak away.\n\n**Part of [TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — real-time token tracking, self-improving crons, persistent cognitive memory. This is one piece of that stack; the repo has dozens more.\n\n👉 **https://github.com/globalcaos/tinkerclaw**\n\n_Clone it. Fork it. Break it. Make it yours._\n\n<why_this_matters>\nA heartbeat agent polling sub-agents with LLM tool calls burns tokens for what is fundamentally an OS-level check. Overseer is a lightweight pull-based bash daemon that monitors sub-agent health, writes a status file every N seconds, and lets the heartbeat handler do zero tool calls when the status file is fresh and healthy.\n</why_this_matters>\n\n## Architecture\n\n```\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 <status-dir>/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads <status-dir>/status.json → summarize or HEARTBEAT_OK\n\n<status-dir> defaults to $XDG_RUNTIME_DIR/overseer, or /tmp/overseer-$UID.\nAsk for it rather than guessing:  scripts/overseer.sh --status-path\n```\n\nThe overseer does all the data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\n## Quick Start\n\n### 1. Start the overseer when spawning sub-agents\n\n```bash\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  &>/dev/null &\n```\n\nScope `--workdir` as narrowly as the work allows: the names of files that change\nunder it are what ends up in the status file. Add `--voice` for spoken alerts\n(counts only), or `--no-filenames` to keep names out of the status file entirely.\n\n### 2. Heartbeat reads the status file\n\n```bash\ncat \"$(scripts/overseer.sh --status-path)\"\n```\n\n### 3. Stop it when you are done\n\n```bash\nscripts/overseer.sh --stop      # stop the daemon\nscripts/overseer.sh --cleanup   # stop it and delete its status, log and pid files\n```\n\nIt also stops itself after two cycles with no sub-agents, but a background process\nyou cannot stop on demand is not really optional, so the off switch is explicit.\n\n### 4. Interpret the status\n\n| Field | Meaning |\n|---|---|\n| `subagents.count` | Active sub-agent sessions |\n| `subagents.details[].stale` | Consecutive cycles with no filesystem changes |\n| `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` |\n| `gateway.health.alive` | Is `openclaw-gateway` running? |\n| `filesystem.changes_since_last` | Files modified since last check |\n\n### 5. Staleness thresholds (at 180s interval)\n\n| stale count | Time | Status | Action |\n|---|---|---|---|\n| 0-1 | 0-3 min | `active`/`idle` | Normal |\n| 2-3 | 6-9 min | `warning` | Voice alert (if --voice) |\n| ≥4 | ≥12 min | `stuck` | Report to user; kill only on request |\n\n<heartbeat_protocol>\nWhen HEARTBEAT.md fires:\n\n1. Read the status file (`overseer.sh --status-path`). If missing or stale (>10 min), restart overseer.\n2. If `subagents.count == 0` for 2+ cycles → overseer auto-exits → reply `HEARTBEAT_OK`.\n3. If all agents `active` → brief one-line status → `HEARTBEAT_OK`.\n4. If any `stuck` → report which labels are stuck to the user. Kill one with `subagents kill` only when the user asks.\n5. Always read the status file fresh; don't cache a previous heartbeat response.\n</heartbeat_protocol>\n\n## Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--interval` | 180 | Seconds between checks |\n| `--workdir` | cwd | Directory to watch for file changes |\n| `--labels` | (all) | Comma-separated labels; only these sub-agents are counted and reported |\n| `--max-stale` | 4 | Cycles before marking `stuck` |\n| `--voice` | off | Local TTS alerts via `jarvis` command. Speaks counts, never filenames |\n| `--voice-files` | off | Speak changed filenames aloud too. Implies `--voice` — anyone in earshot hears what you are working on |\n| `--no-filenames` | off | Never record filenames: the status file gets the change count and nothing else |\n| `--status-dir` | per-user | Where status/log/pid live (also `OVERSEER_DIR`). Created 0700 if missing; an existing dir must be yours, not a symlink, with no group/other permissions, or the script refuses |\n| `--status-path` | — | Print the status file path and exit |\n| `--stop` | — | Stop the running overseer. Signals the pid-file pid only if the lock is held and that pid is your own `overseer.sh`; SIGKILL after 5 s only if it is still that same process |\n| `--cleanup` | — | Stop it, then delete its status, log, marker and pid files (not if it could not be stopped) |\n\n<how_it_works>\nNo AI tokens involved:\n\n1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data.\n2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output.\n3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir.\n4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file.\n5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself.\n6. **Dedup:** `flock` ensures only one overseer instance runs at a time. Child processes run with the lock descriptor closed, so the lock is held exactly as long as the daemon lives.\n7. **Stop:** the between-cycle sleep is interruptible, so SIGTERM from `--stop` is handled immediately, the exit trap removes the marker and pid file, and nothing is left behind.\n</how_it_works>\n\n## What it records, and who can read it\n\nThe only content this daemon handles is filenames. Everything else is counters and\nprocess state. The status file holds the number of files changed under `--workdir`\nsince the last cycle and the basenames of up to five of them — enough to tell you an\nagent is alive, and enough for someone reading the file to tell what you are working on.\n\nSo the runtime directory is per-user and created mode 0700: `$XDG_RUNTIME_DIR/overseer`\nwhen that exists, otherwise `/tmp/overseer-$UID`. Because `/tmp` is shared, the script\ndoes not trust a directory just because it exists: it must be a real directory owned by\nyou with no group or other permissions, or the script exits with an error and changes\nnothing. That same check is what keeps the pid file and lock file trustworthy.\n`--no-filenames` drops names entirely, and voice alerts speak counts unless you pass\n`--voice-files`. The gateway health check only looks at your own `openclaw-gateway` process.\n\nNothing leaves the machine: no network calls, no telemetry, no credentials read. Writes\nare confined to the status directory.\n\n## Running the tests\n\n```bash\nbash tests/test_overseer.sh\n```\n\nStarts throwaway daemons in temp directories and checks the privacy and lifecycle\ncontrols above. It never touches a real overseer or a real workspace.\n\n<cost>\n- Overseer: $0.00 (bash + /proc + one CLI call per cycle)\n- Voice alerts: $0.00 (local sherpa-onnx via `jarvis`)\n- Heartbeat reads status file: $0.00 (one `cat` command)\n- Only cost is the heartbeat model itself (qwen3 local = free)\n</cost>\n\n## Changelog\n\n- 1.1.3 — `--stop` verifies the lock is held and the pid is your own overseer before signalling (no more killing a reused or planted pid); an existing status dir that is a symlink, foreign-owned or group/other-accessible is refused instead of chmod-ed; SIGTERM no longer waits out the sleep interval; `--labels` now actually filters; numeric flags are validated; gateway lookup limited to your own processes; `--cleanup` keeps state if the daemon could not be stopped; heartbeat protocol no longer kills stuck sub-agents without the user asking.\n- 1.1.2 — per-user 0700 status dir, `--no-filenames`, `--voice-files`, `--stop` / `--cleanup`.\n\n## Pairs Well With\n\n- [agent-superpowers](https://clawhub.ai/globalcaos/agent-superpowers) — the three-agent review pipeline that Overseer was built to monitor\n- [smart-model-router](https://clawhub.ai/globalcaos/smart-model-router) — auto-select models for each sub-agent role\n\nhttps://github.com/globalcaos/tinkerclaw\n\n_Clone it. Fork it. Break it. Make it yours._\n\nFile v1.1.3:_meta.json\n\n{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.1.3\",\n  \"publishedAt\": 1789646738026\n}\n\nFile v1.1.3:skill-card.md\n\n## Description:\n\nOverseer watches OpenClaw sub-agents with local OS-level process checks and writes a status file that an agent heartbeat can read without polling sub-agents through model calls.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[globalcaos](https://clawhub.ai/user/globalcaos)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to monitor OpenClaw sub-agents from a local background daemon, detect stalled or stopped work, and have heartbeat handlers read concise status without extra model/tool polling.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The status file may record basenames of recently changed files, which can reveal sensitive project details.\n\nMitigation: Use a narrow --workdir and pass --no-filenames when filename metadata should not be recorded.\n\nRisk: --voice-files can speak changed filenames aloud in the local environment.\n\nMitigation: Avoid --voice-files in shared spaces; default voice alerts speak counts only.\n\nRisk: A local background monitor can continue running after the immediate task is over.\n\nMitigation: Use --stop or --cleanup when monitoring is no longer needed.\n\n## Reference(s):\n\n- [TinkerClaw Subagent Overseer on ClawHub](https://clawhub.ai/globalcaos/skills/subagent-overseer)\n- [TinkerClaw project repository](https://github.com/globalcaos/tinkerclaw)\n- [agent-superpowers](https://clawhub.ai/globalcaos/agent-superpowers)\n- [smart-model-router](https://clawhub.ai/globalcaos/smart-model-router)\n\n## Skill Output:\n\n**Output Type(s):** [text, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline bash commands and status-file guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance centers on running and reading a local overseer status file; no external service output is produced.]\n\n## Skill Version(s):\n\n1.1.3 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.2: 5 files, 13162 bytes\n\nFiles: scripts/overseer.sh (15228b), skill-card.md (2811b), SKILL.md (8641b), tests/test_overseer.sh (5666b), _meta.json (136b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: subagent-overseer\nversion: 1.1.2\ndescription: \"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\"\nmetadata:\n  openclaw:\n    emoji: \"👁️\"\n    notes:\n      security: \"No network calls, no credentials, no writes outside its own status directory. It reads /proc, runs `openclaw sessions list` once per cycle, and counts recently-changed files under --workdir. The one piece of real content it handles is filenames: the status file records the basenames of up to five recently-changed files, which can reveal what you are working on. That directory is per-user and mode 0700 (XDG_RUNTIME_DIR, else /tmp/overseer-$UID); --no-filenames drops the names entirely; voice alerts speak counts only unless you pass --voice-files. It is a background daemon, so it ships its own off switch: --stop and --cleanup.\"\n---\n\n# Sub-Agent Overseer\n\n> One of dozens of skills and plugins in **[TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — a self-improving OpenClaw fork that's been running 24/7 for months.\n\nYou spawned 4 sub-agents. One died 20 minutes ago. You're still waiting.\n\nNobody told you, because nobody was watching — and the thing you'd normally ask to watch them charges you a tool call every time it blinks.\n\nThere's a cheaper kind of eye for this.\n\nOverseer keeps watch over your sub-agents the way the operating system already does — checking which ones are still running and how long each has gone quiet. A tiny background process writes down their health every few seconds, so when your agent's heartbeat wakes up, it just reads that note and goes back to sleep. While everything is healthy it spends nothing: no model, no questions, no busywork. The moment an agent stalls or dies, the note says so, and you can act before another twenty minutes leak away.\n\n**Part of [TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — real-time token tracking, self-improving crons, persistent cognitive memory. This is one piece of that stack; the repo has dozens more.\n\n👉 **https://github.com/globalcaos/tinkerclaw**\n\n_Clone it. Fork it. Break it. Make it yours._\n\n<why_this_matters>\nA heartbeat agent polling sub-agents with LLM tool calls burns tokens for what is fundamentally an OS-level check. Overseer is a lightweight pull-based bash daemon that monitors sub-agent health, writes a status file every N seconds, and lets the heartbeat handler do zero tool calls when the status file is fresh and healthy.\n</why_this_matters>\n\n## Architecture\n\n```\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 <status-dir>/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads <status-dir>/status.json → summarize or HEARTBEAT_OK\n\n<status-dir> defaults to $XDG_RUNTIME_DIR/overseer, or /tmp/overseer-$UID.\nAsk for it rather than guessing:  scripts/overseer.sh --status-path\n```\n\nThe overseer does all the data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\n## Quick Start\n\n### 1. Start the overseer when spawning sub-agents\n\n```bash\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  &>/dev/null &\n```\n\nScope `--workdir` as narrowly as the work allows: the names of files that change\nunder it are what ends up in the status file. Add `--voice` for spoken alerts\n(counts only), or `--no-filenames` to keep names out of the status file entirely.\n\n### 2. Heartbeat reads the status file\n\n```bash\ncat \"$(scripts/overseer.sh --status-path)\"\n```\n\n### 3. Stop it when you are done\n\n```bash\nscripts/overseer.sh --stop      # stop the daemon\nscripts/overseer.sh --cleanup   # stop it and delete its status, log and pid files\n```\n\nIt also stops itself after two cycles with no sub-agents, but a background process\nyou cannot stop on demand is not really optional, so the off switch is explicit.\n\n### 4. Interpret the status\n\n| Field | Meaning |\n|---|---|\n| `subagents.count` | Active sub-agent sessions |\n| `subagents.details[].stale` | Consecutive cycles with no filesystem changes |\n| `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` |\n| `gateway.health.alive` | Is `openclaw-gateway` running? |\n| `filesystem.changes_since_last` | Files modified since last check |\n\n### 5. Staleness thresholds (at 180s interval)\n\n| stale count | Time | Status | Action |\n|---|---|---|---|\n| 0-1 | 0-3 min | `active`/`idle` | Normal |\n| 2-3 | 6-9 min | `warning` | Voice alert (if --voice) |\n| ≥4 | ≥12 min | `stuck` | Agent should investigate/kill |\n\n<heartbeat_protocol>\nWhen HEARTBEAT.md fires:\n\n1. Read the status file (`overseer.sh --status-path`). If missing or stale (>10 min), restart overseer.\n2. If `subagents.count == 0` for 2+ cycles → overseer auto-exits → reply `HEARTBEAT_OK`.\n3. If all agents `active` → brief one-line status → `HEARTBEAT_OK`.\n4. If any `stuck` → report which labels are stuck → consider killing via `subagents kill`.\n5. Always read the status file fresh; don't cache a previous heartbeat response.\n</heartbeat_protocol>\n\n## Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--interval` | 180 | Seconds between checks |\n| `--workdir` | cwd | Directory to watch for file changes |\n| `--labels` | (all) | Comma-separated labels to filter |\n| `--max-stale` | 4 | Cycles before marking `stuck` |\n| `--voice` | off | Local TTS alerts via `jarvis` command. Speaks counts, never filenames |\n| `--voice-files` | off | Speak changed filenames aloud too. Implies `--voice` — anyone in earshot hears what you are working on |\n| `--no-filenames` | off | Never record filenames: the status file gets the change count and nothing else |\n| `--status-dir` | per-user | Where status/log/pid live (also `OVERSEER_DIR`) |\n| `--status-path` | — | Print the status file path and exit |\n| `--stop` | — | Stop the running overseer |\n| `--cleanup` | — | Stop it, then delete its status, log, marker and pid files |\n\n<how_it_works>\nNo AI tokens involved:\n\n1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data.\n2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output.\n3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir.\n4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file.\n5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself.\n6. **Dedup:** `flock` ensures only one overseer instance runs at a time.\n</how_it_works>\n\n## What it records, and who can read it\n\nThe only content this daemon handles is filenames. Everything else is counters and\nprocess state. The status file holds the number of files changed under `--workdir`\nsince the last cycle and the basenames of up to five of them — enough to tell you an\nagent is alive, and enough for someone reading the file to tell what you are working on.\n\nSo the runtime directory is per-user and created mode 0700: `$XDG_RUNTIME_DIR/overseer`\nwhen that exists, otherwise `/tmp/overseer-$UID`. (Before 1.1.2 it was `/tmp/overseer`,\none shared directory for every user on the machine. If you have tooling pinned to that\npath, `--status-dir /tmp/overseer` restores it — knowing what that means.) `--no-filenames`\ndrops names entirely, and voice alerts speak counts unless you pass `--voice-files`.\n\nNothing leaves the machine: no network calls, no telemetry, no credentials read. Writes\nare confined to the status directory.\n\n## Running the tests\n\n```bash\nbash tests/test_overseer.sh\n```\n\nStarts throwaway daemons in temp directories and checks the privacy and lifecycle\ncontrols above. It never touches a real overseer or a real workspace.\n\n<cost>\n- Overseer: $0.00 (bash + /proc + one CLI call per cycle)\n- Voice alerts: $0.00 (local sherpa-onnx via `jarvis`)\n- Heartbeat reads status file: $0.00 (one `cat` command)\n- Only cost is the heartbeat model itself (qwen3 local = free)\n</cost>\n\n## Pairs Well With\n\n- [agent-superpowers](https://clawhub.ai/globalcaos/agent-superpowers) — the three-agent review pipeline that Overseer was built to monitor\n- [smart-model-router](https://clawhub.ai/globalcaos/smart-model-router) — auto-select models for each sub-agent role\n\nhttps://github.com/globalcaos/tinkerclaw\n\n_Clone it. Fork it. Break it. Make it yours._\n\nFile v1.1.2:_meta.json\n\n{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.1.2\",\n  \"publishedAt\": 1788943862435\n}\n\nFile v1.1.2:skill-card.md\n\n## Description:\n\nTinkerClaw Subagent Overseer monitors OpenClaw sub-agents with a local Bash daemon, checks process and filesystem activity, and writes a status file that heartbeat agents can read without repeated model/tool polling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[globalcaos](https://clawhub.ai/user/globalcaos)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to monitor OpenClaw sub-agents from the operating system side, detect idle or stuck sessions, and let heartbeat agents read a local status file instead of repeatedly polling with model/tool calls.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill runs a local background daemon that monitors OpenClaw sub-agents and writes daemon state to disk.\n\nMitigation: Install it only when local sub-agent monitoring is desired, use a private user-owned status directory, and stop or clean up the daemon with the documented lifecycle commands when monitoring is no longer needed.\n\nRisk: The status file can include basenames of recently changed files under the watched work directory.\n\nMitigation: Scope --workdir narrowly for the active task and use --no-filenames for sensitive projects.\n\nRisk: The fallback status directory is under /tmp, which may be less appropriate on shared machines.\n\nMitigation: Prefer XDG_RUNTIME_DIR or pass a private --status-dir with user-only permissions.\n\nRisk: The optional --voice-files mode can speak changed filenames aloud.\n\nMitigation: Use default voice alerts or --voice without --voice-files unless filename disclosure to people nearby is acceptable.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/globalcaos/skills/subagent-overseer)\n- [TinkerClaw repository link from skill materials](https://github.com/globalcaos/tinkerclaw)\n- [agent-superpowers related ClawHub skill](https://clawhub.ai/globalcaos/agent-superpowers)\n- [smart-model-router related ClawHub skill](https://clawhub.ai/globalcaos/smart-model-router)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, JSON, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands; the daemon writes JSON status files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Status output includes process health, sub-agent counts, staleness state, filesystem change counts, and optionally recent file basenames.]\n\n## Skill Version(s):\n\n1.1.2 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.1: 3 files, 5481 bytes\n\nFiles: _meta.json (136b), scripts/overseer.sh (8620b), SKILL.md (4179b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: subagent-overseer\nversion: 1.1.0\ndescription: \"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\"\nmetadata:\n  openclaw:\n    emoji: \"👁️\"\n    notes:\n      security: \"No network calls. Reads process status and filesystem diffs only. Pure bash daemon.\"\n---\n\n# 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\n## Architecture\n\n```\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\n**Key principle:** The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\n## Quick Start\n\n### 1. Start the overseer when spawning sub-agents\n\n```bash\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  --voice \\\n  &>/dev/null &\n```\n\n### 2. Heartbeat reads the status file\n\n```bash\ncat /tmp/overseer/status.json\n```\n\n### 3. Interpret the status\n\n| Field | Meaning |\n|---|---|\n| `subagents.count` | Active sub-agent sessions |\n| `subagents.details[].stale` | Consecutive cycles with no filesystem changes |\n| `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` |\n| `gateway.health.alive` | Is `openclaw-gateway` running? |\n| `filesystem.changes_since_last` | Files modified since last check |\n\n### 4. Staleness thresholds (at 180s interval)\n\n| stale count | Time | Status | Action |\n|---|---|---|---|\n| 0-1 | 0-3 min | `active`/`idle` | Normal |\n| 2-3 | 6-9 min | `warning` | Voice alert (if --voice) |\n| ≥4 | ≥12 min | `stuck` | Agent should investigate/kill |\n\n## Heartbeat Handler Protocol\n\nWhen HEARTBEAT.md fires:\n\n1. **Read `/tmp/overseer/status.json`** — if missing or stale (>10 min), restart overseer\n2. **If `subagents.count == 0` for 2+ cycles** → overseer auto-exits → reply `HEARTBEAT_OK`\n3. **If all agents `active`** → brief one-line status → `HEARTBEAT_OK`\n4. **If any `stuck`** → report which labels are stuck → consider killing via `subagents kill`\n5. **Never cache a previous heartbeat response.** Always read the status file fresh.\n\n## Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--interval` | 180 | Seconds between checks |\n| `--workdir` | cwd | Directory to watch for file changes |\n| `--labels` | (all) | Comma-separated labels to filter |\n| `--max-stale` | 4 | Cycles before marking `stuck` |\n| `--voice` | off | Local TTS alerts via `jarvis` command |\n\n## How It Works (No AI Tokens)\n\n1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data.\n2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output.\n3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir.\n4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file.\n5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself.\n6. **Dedup:** `flock` ensures only one overseer instance runs at a time.\n\n## Cost\n\n- Overseer: **$0.00** (bash + /proc + one CLI call per cycle)\n- Voice alerts: **$0.00** (local sherpa-onnx via `jarvis`)\n- Heartbeat reads status file: **$0.00** (one `cat` command)\n- Only cost is the heartbeat model itself (qwen3 local = free)\n\n## Pairs Well With\n\n- [agent-superpowers](https://clawhub.com/globalcaos/agent-superpowers) — the three-agent review pipeline that Overseer was built to monitor\n- [smart-model-router](https://clawhub.com/globalcaos/smart-model-router) — auto-select models for each sub-agent role\n\n👉 **https://github.com/globalcaos/tinkerclaw**\n\n_Clone it. Fork it. Break it. Make it yours._\n\nFile v1.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1780764642927\n}\n\nArchive v1.1.0: 3 files, 5481 bytes\n\nFiles: scripts/overseer.sh (8620b), SKILL.md (4179b), _meta.json (136b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: subagent-overseer\nversion: 1.1.0\ndescription: \"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\"\nmetadata:\n  openclaw:\n    emoji: \"👁️\"\n    notes:\n      security: \"No network calls. Reads process status and filesystem diffs only. Pure bash daemon.\"\n---\n\n# 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\n## Architecture\n\n```\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\n**Key principle:** The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\n## Quick Start\n\n### 1. Start the overseer when spawning sub-agents\n\n```bash\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  --voice \\\n  &>/dev/null &\n```\n\n### 2. Heartbeat reads the status file\n\n```bash\ncat /tmp/overseer/status.json\n```\n\n### 3. Interpret the status\n\n| Field | Meaning |\n|---|---|\n| `subagents.count` | Active sub-agent sessions |\n| `subagents.details[].stale` | Consecutive cycles with no filesystem changes |\n| `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` |\n| `gateway.health.alive` | Is `openclaw-gateway` running? |\n| `filesystem.changes_since_last` | Files modified since last check |\n\n### 4. Staleness thresholds (at 180s interval)\n\n| stale count | Time | Status | Action |\n|---|---|---|---|\n| 0-1 | 0-3 min | `active`/`idle` | Normal |\n| 2-3 | 6-9 min | `warning` | Voice alert (if --voice) |\n| ≥4 | ≥12 min | `stuck` | Agent should investigate/kill |\n\n## Heartbeat Handler Protocol\n\nWhen HEARTBEAT.md fires:\n\n1. **Read `/tmp/overseer/status.json`** — if missing or stale (>10 min), restart overseer\n2. **If `subagents.count == 0` for 2+ cycles** → overseer auto-exits → reply `HEARTBEAT_OK`\n3. **If all agents `active`** → brief one-line status → `HEARTBEAT_OK`\n4. **If any `stuck`** → report which labels are stuck → consider killing via `subagents kill`\n5. **Never cache a previous heartbeat response.** Always read the status file fresh.\n\n## Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--interval` | 180 | Seconds between checks |\n| `--workdir` | cwd | Directory to watch for file changes |\n| `--labels` | (all) | Comma-separated labels to filter |\n| `--max-stale` | 4 | Cycles before marking `stuck` |\n| `--voice` | off | Local TTS alerts via `jarvis` command |\n\n## How It Works (No AI Tokens)\n\n1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data.\n2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output.\n3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir.\n4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file.\n5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself.\n6. **Dedup:** `flock` ensures only one overseer instance runs at a time.\n\n## Cost\n\n- Overseer: **$0.00** (bash + /proc + one CLI call per cycle)\n- Voice alerts: **$0.00** (local sherpa-onnx via `jarvis`)\n- Heartbeat reads status file: **$0.00** (one `cat` command)\n- Only cost is the heartbeat model itself (qwen3 local = free)\n\n## Pairs Well With\n\n- [agent-superpowers](https://clawhub.com/globalcaos/agent-superpowers) — the three-agent review pipeline that Overseer was built to monitor\n- [smart-model-router](https://clawhub.com/globalcaos/smart-model-router) — auto-select models for each sub-agent role\n\n👉 **https://github.com/globalcaos/tinkerclaw**\n\n_Clone it. Fork it. Break it. Make it yours._\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1773157189071\n}\n\nArchive v1.0.0: 3 files, 5249 bytes\n\nFiles: scripts/overseer.sh (8620b), SKILL.md (3784b), _meta.json (136b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: subagent-overseer\ndescription: 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.\n---\n\n# 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\n## Architecture\n\n```\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\n**Key principle:** The overseer does all data collection. The heartbeat handler does zero tool calls if the status file is fresh and healthy.\n\n## Quick Start\n\n### 1. Start the overseer when spawning sub-agents\n\n```bash\nsetsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  --voice \\\n  &>/dev/null &\n```\n\n### 2. Heartbeat reads the status file\n\n```bash\ncat /tmp/overseer/status.json\n```\n\n### 3. Interpret the status\n\n| Field | Meaning |\n|---|---|\n| `subagents.count` | Active sub-agent sessions |\n| `subagents.details[].stale` | Consecutive cycles with no filesystem changes |\n| `subagents.details[].status` | `active` / `idle` / `warning` / `stuck` |\n| `gateway.health.alive` | Is `openclaw-gateway` running? |\n| `filesystem.changes_since_last` | Files modified since last check |\n\n### 4. Staleness thresholds (at 180s interval)\n\n| stale count | Time | Status | Action |\n|---|---|---|---|\n| 0-1 | 0-3 min | `active`/`idle` | Normal |\n| 2-3 | 6-9 min | `warning` | Voice alert (if --voice) |\n| ≥4 | ≥12 min | `stuck` | Agent should investigate/kill |\n\n## Heartbeat Handler Protocol\n\nWhen HEARTBEAT.md fires:\n\n1. **Read `/tmp/overseer/status.json`** — if missing or stale (>10 min), restart overseer\n2. **If `subagents.count == 0` for 2+ cycles** → overseer auto-exits → reply `HEARTBEAT_OK`\n3. **If all agents `active`** → brief one-line status → `HEARTBEAT_OK`\n4. **If any `stuck`** → report which labels are stuck → consider killing via `subagents kill`\n5. **Never cache a previous heartbeat response.** Always read the status file fresh.\n\n## Flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `--interval` | 180 | Seconds between checks |\n| `--workdir` | cwd | Directory to watch for file changes |\n| `--labels` | (all) | Comma-separated labels to filter |\n| `--max-stale` | 4 | Cycles before marking `stuck` |\n| `--voice` | off | Local TTS alerts via `jarvis` command |\n\n## How It Works (No AI Tokens)\n\n1. **Gateway health:** Reads `/proc/<pid>/status` for CPU, memory, threads, FD count. Pure kernel data.\n2. **Sub-agent list:** Single `openclaw sessions list` call per cycle. Parses grep output.\n3. **Filesystem diff:** `find -newer marker` — detects any file writes in the workdir.\n4. **Status file:** JSON written atomically (write to temp, `mv` into place). Any reader sees a complete file.\n5. **Self-exit:** If no sub-agents for 2 consecutive cycles, the overseer stops itself.\n6. **Dedup:** `flock` ensures only one overseer instance runs at a time.\n\n## Cost\n\n- Overseer: **$0.00** (bash + /proc + one CLI call per cycle)\n- Voice alerts: **$0.00** (local sherpa-onnx via `jarvis`)\n- Heartbeat reads status file: **$0.00** (one `cat` command)\n- Only cost is the heartbeat model itself (qwen3 local = free)\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1771698479094\n}","readmeExcerpt":"Skill: TinkerClaw Subagent Overseer Owner: globalcaos Summary: You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats. Tags: latest:1.1.3 Version history: v1.1.3 | 2026-09-17T12:05:38.026Z | user --stop now signals only when all of these hold: the pid is a number, the flock ","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"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 <status-dir>/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads <status-dir>/status.json → summarize or HEARTBEAT_OK\n\n<status-dir> defaults to $XDG_RUNTIME_DIR/overseer, or /tmp/overseer-$UID.\nAsk for it rather than guessing:  scripts/overseer.sh --status-path"},{"language":"bash","snippet":"setsid scripts/overseer.sh \\\n  --workdir /path/to/repo \\\n  --interval 180 \\\n  --max-stale 4 \\\n  &>/dev/null &"},{"language":"bash","snippet":"cat \"$(scripts/overseer.sh --status-path)\""},{"language":"bash","snippet":"scripts/overseer.sh --stop      # stop the daemon\nscripts/overseer.sh --cleanup   # stop it and delete its status, log and pid files"},{"language":"bash","snippet":"bash tests/test_overseer.sh"},{"language":"text","snippet":"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 <status-dir>/status.json  (atomic mv)\n\nheartbeat (agent, every 3min)\n    └── reads <status-dir>/status.json → summarize or HEARTBEAT_OK\n\n<status-dir> defaults to $XDG_RUNTIME_DIR/overseer, or /tmp/overseer-$UID.\nAsk for it rather than guessing:  scripts/overseer.sh --status-path"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: subagent-overseer\nversion: 1.1.3\ndescription: \"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats.\"\nmetadata:\n  openclaw:\n    emoji: \"👁️\"\n    notes:\n      security: \"No network calls, no credentials, no writes outside its own status directory. It reads /proc, runs `openclaw sessions list` once per cycle, and counts recently-changed files under --workdir. The one piece of real content it handles is filenames: the status file records the basenames of up to five recently-changed files, which can reveal what you are working on. That directory is per-user and mode 0700 (XDG_RUNTIME_DIR, else /tmp/overseer-$UID); an existing directory that is a symlink, owned by someone else, or group/other-accessible is refused rather than used. --no-filenames drops the names entirely; voice alerts speak counts only unless you pass --voice-files. It is a background daemon with its own off switch: --stop signals the recorded pid only if the lock is held and that pid is your own overseer.sh process, so a stale or planted pid file cannot make it kill anything else.\"\n---\n\n# Sub-Agent Overseer\n\n> One of dozens of skills and plugins in **[TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — a self-improving OpenClaw fork that's been running 24/7 for months.\n\nYou spawned 4 sub-agents. One died 20 minutes ago. You're still waiting.\n\nNobody told you, because nobody was watching — and the thing you'd normally ask to watch them charges you a tool call every time it blinks.\n\nThere's a cheaper kind of eye for this.\n\nOverseer keeps watch over your sub-agents the way the operating system already does — checking which ones are still running and how long each has gone quiet. A tiny background process writes down their health every few minutes (every 180 s by default, set with `--interval`), so when your agent's heartbeat wakes up, it just reads that note and goes back to sleep. While everything is healthy it spends nothing: no model, no questions, no busywork. The moment an agent stalls or dies, the note says so, and you can act before another twenty minutes leak away.\n\n**Part of [TinkerClaw](https://github.com/globalcaos/tinkerclaw)** — real-time token tracking, self-improving crons, persistent cognitive memory. This is one piece of that stack; the repo has dozens more.\n\n👉 **https://github.com/globalcaos/tinkerclaw**\n\n_Clone it. Fork it. Break it. Make it yours._\n\n<why_this_matters>\nA heartbeat agent polling sub-agents with LLM tool calls burns tokens for what is fundamentally an OS-level check. Overseer is a lightweight pull-based bash daemon that monitors sub-agent health, writes a status file every N seconds, and lets the heartbeat handler do zero tool calls when the status file is fresh and healthy.\n</why_this_matters>\n\n## Architecture\n\n```\noverseer.sh (bash, runs in background)\n    ├── /proc/<pid>  → gateway alive? "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7623hrcwt6rg73a67xw3wyx580asdw\",\n  \"slug\": \"subagent-overseer\",\n  \"version\": \"1.1.3\",\n  \"publishedAt\": 1789646738026\n}"},{"path":"skill-card.md","content":"## Description:\n\nOverseer watches OpenClaw sub-agents with local OS-level process checks and writes a status file that an agent heartbeat can read without polling sub-agents through model calls.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[globalcaos](https://clawhub.ai/user/globalcaos)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to monitor OpenClaw sub-agents from a local background daemon, detect stalled or stopped work, and have heartbeat handlers read concise status without extra model/tool polling.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The status file may record basenames of recently changed files, which can reveal sensitive project details.\n\nMitigation: Use a narrow --workdir and pass --no-filenames when filename metadata should not be recorded.\n\nRisk: --voice-files can speak changed filenames aloud in the local environment.\n\nMitigation: Avoid --voice-files in shared spaces; default voice alerts speak counts only.\n\nRisk: A local background monitor can continue running after the immediate task is over.\n\nMitigation: Use --stop or --cleanup when monitoring is no longer needed.\n\n## Reference(s):\n\n- [TinkerClaw Subagent Overseer on ClawHub](https://clawhub.ai/globalcaos/skills/subagent-overseer)\n- [TinkerClaw project repository](https://github.com/globalcaos/tinkerclaw)\n- [agent-superpowers](https://clawhub.ai/globalcaos/agent-superpowers)\n- [smart-model-router](https://clawhub.ai/globalcaos/smart-model-router)\n\n## Skill Output:\n\n**Output Type(s):** [text, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline bash commands and status-file guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance centers on running and reading a local overseer status file; no external service output is produced.]\n\n## Skill Version(s):\n\n1.1.3 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats. Skill: TinkerClaw Subagent Overseer Owner: globalcaos Summary: You spawned 4 sub-agents. One died 20 minutes ago. You're still waiting. Overseer watches them so you don't have to — zero tokens, pure OS-level process checks. No polling loops, no wasted heartbeats. Tags: latest:1.1.3 Version history: v1.1.3 | 2026-09-17T12:05:38.026Z | user --stop now signals only when all of these hold: the pid is a number, the flock","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1295,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T15:36:42.239Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:43:11.330Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}