subagent-tracker

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

• User says: "agent status", "track subagents", "see what the sub-agent is doing", "show progress", "show subagent progress", "why didn't the agent come back", "sub-agent never responded"
• After delegation: user wants a progress/loading-style view — run the tracker and summarize active subagents and recent tool calls
• Debugging: sub-agent was assigned (e.g. "Using: Kimi k2.5") but no result showed in chat — list runs and sessions, tail transcripts, report what the sub-agent is doing or did

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 <session-id|key> [--json]

python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py tail <session-id> [--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 "<task string>" --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

• One phrase: Say “agent status”, “track subagents”, or “show subagent progress” and the orchestrator runs the tracker and reports (Agent 1, Agent 2, … with Task X/Y and model).
• Full visibility — List active subagents, view status and tokens, tail transcript events (tool calls, thinking).
• Works with the swarm — Map task → session via subagents/runs.json; when runs include taskIndex and totalTasks, the tracker shows “Task X/Y” per agent.
• Duplicate prevention — 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 <session-id> / tail <session-id> for detail.

Features

• List active subagents – Sessions with status (recent activity, model, tokens)
• View subagent details – Tool calls, tokens, transcript line count
• Tail subagent logs – Recent transcript events (tool calls, thinking)
• Map task → session – 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 <sessionId> 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).