Subagent Tracker
by @austindixson
Say "agent status" and get updates on all subagent progress. Track subagent actions while they run; list active subagents, status, and tail transcripts. Inst...
clawhub install subagent-tracker📖 About This Skill
name: subagent-tracker displayName: Subagent Tracker description: Say "agent status" and get updates on all subagent progress. Track subagent actions while they run; list active subagents, status, and tail transcripts. Install for power users using the agent swarm. version: 1.2.0
Subagent Tracker
Description
Say "agent status" and get updates on all subagent progress. Track subagent actions while they run; list active subagents, status, and tail transcripts. Install for power users using the agent swarm.
Subagent Tracker
Say “agent status” and get an update on all subagent progress—who’s running, what they’re doing, and when tasks complete. The TUI doesn’t show a live “sub-agent working…” indicator; subagent-tracker is how you see what your agent swarm is doing.
Installation
ClawHub: Update clawhub install and ClawHub links when the new ClawHub instance is live.
npm install -g clawhub
clawhub install subagent-tracker
Or clone: git clone https://github.com/RuneweaverStudios/subagent-tracker.git workspace/skills/subagent-tracker
Usage
| You say | What happens | |--------|----------------| | "agent status" | Orchestrator runs tracker, reports active subagents (Agent 1, Agent 2, … with Task X/Y and model). | | "track subagents" / "show subagent progress" | Same: list active subagents and optional status/tail for detail. | | "what's the sub-agent doing?" | Tracker list + summary; optionally status for a specific session. | | "why didn't the agent come back?" | Tracker shows what ran or is running; orchestrator can tail transcript and report. |
Examples
List subagents active in the last 30 minutes:
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py list --active 30
Status for a session (ID from list or runs.json):
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py status e1e51315-9766-4604-85b4-58b9e96c39ef
Tail last 15 transcript events:
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py tail e1e51315-9766-4604-85b4-58b9e96c39ef --lines 15
Run all tracker checks locally (list + status + tail on first active subagent):
/Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/test-subagent-tracker.sh
Commands
From any cwd (e.g. TUI exec), use the skill path:
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py list [--active MINUTES] [--json] [--summary]
(Use --summary for a single "Here are your active subagents" block with Agent 1, Agent 2, … and Task X/Y when available; report it once, do not duplicate.)python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py status [--json]
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py tail [--lines N]
Prevent duplicate subagent tasks (run before sessions_spawn):
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py check-duplicate --task "" --json
If output has "duplicate": true, do not call sessions_spawn; reply that the task is already running. The orchestrator rule runs this automatically before spawning.Session IDs come from list or from subagents/runs.json (extract from childSessionKey, e.g. agent:main:subagent:UUID → use UUID).
Pain point
When you queue multiple tasks (poem, bug fix, research), you have no built-in view of which subagents are active or how far along they are. Without this skill, “agent status” or “what’s the sub-agent doing?” can’t be answered.
Benefits
subagents/runs.json; when runs include taskIndex and totalTasks, the tracker shows “Task X/Y” per agent.check-duplicate runs before sessions_spawn so the same task isn’t run twice (saves tokens and lag).Encouraged for power users: If you use Agent Swarm and handle multiple queued tasks, download subagent-tracker so you can say “agent status” and stay updated.
Chat visibility and "agents never come back"
Why results sometimes don't appear: The orchestrator must wait for sessions_spawn to return before replying. If it replies with "I'll let you know once it has findings!" and ends the turn, the sub-agent result never gets into the chat. The rule "Wait for spawn before replying" in the orchestrator delegate rule addresses this.
Progress/loading: The TUI does not show a live "Sub-agent working…" indicator. To see progress, the user must ask (e.g. "show subagent progress", "what's the sub-agent doing?", "track subagents"). The orchestrator then runs the tracker and reports. Use list --active 30 --summary for a single block (e.g. "Here are your active subagents:" with "Agent 1 (Task 2/5): model (age)" per line). The orchestrator must output this block once only—never repeat it. Optionally list --active 30 then status / tail for detail.
Features
subagents/runs.json has task, childSessionKey, runId; when entries include taskIndex and totalTasks, the tracker shows "Task X/Y" (e.g. Task 3/5) per agent.Orchestrator behavior
When the user asks to track or see progress of subagents:
1. Run subagent_tracker.py list --active 30 --summary (absolute path above). The output is a single block with "Here are your active subagents:" and one line per agent (Agent 1, Agent 2, … with Task X/Y when in runs.json).
2. Paste that block once in your reply; do not repeat it or add a second copy of the list. Optionally run status for detail.
3. If you add a line about completed subagents, do it once at the end. Optionally summarize in plain language: e.g. "One sub-agent is running (Kimi k2.5). It’s been active for 2m; last actions: write, exec (npm install)."
When the user says sub-agents never come back or no results in chat:
1. Acknowledge the issue (orchestrator should wait for sessions_spawn before replying; see delegate rule).
2. Run the tracker to show what *is* running or what recently ran: list, then status/tail for recent sessions, and report.
Integration with heartbeats
In HEARTBEAT.md you can add:
Subagent checks
Check for stalled subagents (>30 min inactive)
Notify when subagents complete
How it works
The tracker reads OpenClaw's session store (agents/main/sessions/) and JSONL transcripts. It does not require extra dependencies (Python standard library).
💡 Examples
List subagents active in the last 30 minutes:
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py list --active 30
Status for a session (ID from list or runs.json):
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py status e1e51315-9766-4604-85b4-58b9e96c39ef
Tail last 15 transcript events:
python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py tail e1e51315-9766-4604-85b4-58b9e96c39ef --lines 15
Run all tracker checks locally (list + status + tail on first active subagent):
/Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/test-subagent-tracker.sh