Skill: austindixson/subagent-tracker (version 1.2.0)

--- 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. ```bash 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:** ```bash 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):** ```bash python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py status e1e51315-9766-4604-85b4-58b9e96c39ef ``` **Tail last 15 transcript events:** ```bash 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):** ```bash /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/test-subagent-tracker.sh ``` ## Commands From any cwd (e.g. TUI exec), use the skill path: ```bash 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.) ```bash python3 /Users/ghost/.openclaw/workspace/skills/subagent-tracker/scripts/subagent_tracker.py status <session-id|key> [--json] ``` ```bash 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):** ```bash 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: ```markdown ## 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).


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)