About

Imported from ulises-jeremias/agent-toolkit (plugins/agent-toolkit-complete/.github/skills/swarm-observer/SKILL.md). Install upstream with npx skills add ulises-jeremias/agent-toolkit --skill swarm-observer. Copyright stays with the author.

Swarm Observer

Name: swarm-observer
Author: ulises-jeremias

Monitor any agent-toolkit swarm run, diagnose stuck handoffs or backend drift, and recover without losing windows. Works for both Herdr (tabs) and tmux (isolated socket agent-toolkit-swarm-<run-id>). Integrates with swarm's eager-window model (every role starts as Waiting for handoff: <pred> -> <role> with agent_waiting trace).

When to use

A swarm was launched and the user asks "is it done?", "what's the status?", "show logs", or "attach".
A handoff has been active for >5m (955be6f6e2c... pattern) or worktree_failed.
Herdr shows extra workspaces (w7-wA) for headless runs — the get_backend("headless") fallback case.
User wants to reuse the same run for a new request and needs to know if windows are still alive.

Prerequisites

Run lives under .agent-toolkit/swarm/runs/<run-id>/state.json (filesystem is authoritative).
Know run-id (20260807T...-xxxxxx) from swarm start --json or swarm list --json.
Shell is detected (_user_shell(): $SHELL → pwd.getpwuid → /usr/bin/zsh fallback, executed as <shell> -lc).

Workflow

1. List and pick the run

agent-toolkit swarm list --json | jq
agent-toolkit swarm status --run-id <run-id>
agent-toolkit swarm status --run-id <run-id> --json | jq '.handoffs,.worktrees,.trace'

2. Inspect handoffs and trace

agent-toolkit swarm handoffs --run-id <run-id>
agent-toolkit swarm handoffs --run-id <run-id> --json | jq '.[] | {id,from,to,status,artifact,auto}'
# Active that should have auto-completed:
#   where to==from_role and handoff create --to == that role -> auto:true

Trace keys to watch: agent_waiting, handoff_completed auto:true, worktree_failed, headless_fallback.

3. Tail logs and attach

agent-toolkit swarm logs --run-id <run-id> --follow
agent-toolkit swarm logs --run-id <run-id> --role reviewer --follow
agent-toolkit swarm attach --run-id <run-id>          # herdr: workspace focus; tmux: attach -L agent-toolkit-swarm-<run-id>
herdr workspace list --json 2>&1 | jq '.[] | {id,name,status}'
tmux -L agent-toolkit-swarm-<run-id> capture-pane -t <window> -p | tail -n 80

4. Diagnose

Symptom	Cause	Fix
`Waiting for handoff: a -> b	role: b` stuck >5m	`active` handoff never `task complete`
`worktree_failed`	`find_repo_root` failed (`git rev-parse --git-common-dir` on `.git` file)	Re-run `handoff create` — fixed via `AGENT_TOOLKIT_SWARM_RUN_ID` export + path extract
Extra Herdr workspaces `w7-wA` with `headless`	`get_backend("headless")` returned `HerdrBackend`	Patch `backends/__init__.py` to return headless/noop backend; then `herdr workspace delete <id>` for orphans
Shell shows `bash` while user uses `zsh`	Hardcoded `bash -lc`	Fixed via `_user_shell()` / `_shell_base()` — verify `ps -o comm= -p <pid>` shows `zsh`

5. Recover or reuse

# Complete stuck handoff and provision next role (worktree/tab + agent start)
agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/fix.md --run-id <run-id>

# Reuse same windows for a new request (no new run needed)
agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/new-task.md --run-id <run-id>
# Chain re-triggers: implementer -> reviewer -> integrator via file handoffs

# Only create a new run when isolated branch is required
agent-toolkit swarm start --recipe pair --ui herdr --runner opencode --model-profile balanced --attach "new isolated task"

Boundaries

Never edit .agent-toolkit/swarm/runs/<run-id>/state.json by hand; use handoff create / task complete / promote.
Never create new Herdr workspaces for headless — fix the backend fallback instead.
For tmux, always use isolated socket -L agent-toolkit-swarm-<run-id>; never the default server.

Delegates to

Need	Skill/Command
Show failure snippet before fixing	`swarm-handoff`
Recreate worktree	`agent-toolkit swarm handoff create` (auto-provisions)
Review code produced by swarm	`code-reviewer`, `security-reviewer`
Create PR after promotion	`github-cli-workflow`

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/ulises-jeremias-agent-toolkit-swarm-observer/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

ulises-jeremias-agent-toolkit-swarm-observer.ocm.jsonjson

{
  "ocm": "1",
  "id": "ulises-jeremias-agent-toolkit-swarm-observer",
  "kind": "skill",
  "name": "swarm-observer",
  "description": "Observe, diagnose, and recover Agent Toolkit swarm runs via status, handoffs, logs, and attach with worktree and shell awareness.",
  "publisher": "ulises-jeremias",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "swarm",
      "observer",
      "herdr",
      "tmux",
      "handoff",
      "worktree",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Observe, diagnose, and recover Agent Toolkit swarm runs via status, handoffs, logs, and attach with worktree and shell awareness."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/ulises-jeremias/agent-toolkit",
      "path": "plugins/agent-toolkit-complete/.github/skills/swarm-observer/SKILL.md",
      "ref": "6b18889459d548230c06f6efe312c0fa13c611f8",
      "url": "https://github.com/ulises-jeremias/agent-toolkit/blob/6b18889459d548230c06f6efe312c0fa13c611f8/plugins/agent-toolkit-complete/.github/skills/swarm-observer/SKILL.md",
      "key": "ulises-jeremias/agent-toolkit/plugins/agent-toolkit-complete/.github/skills/swarm-observer/SKILL.md"
    }
  },
  "instructions": "# Swarm Observer\n\nMonitor any `agent-toolkit swarm` run, diagnose stuck handoffs or backend drift, and recover without losing windows. Works for both **Herdr** (tabs) and **tmux** (isolated socket `agent-toolkit-swarm-<run-id>`). Integrates with swarm's eager-window model (every role starts as `Waiting for handoff: <pred> -> <role>` with `agent_waiting` trace).\n\n## When to use\n\n- A swarm was launched and the user asks \"is it done?\", \"what's the status?\", \"show logs\", or \"attach\".\n- A handoff has been `active` for >5m (`955be6f6e2c...` pattern) or `worktree_failed`.\n- Herdr shows extra workspac",
  "cost": {
    "context_tokens": 1109
  }
}

Fetch it by URL: GET /api/v1/registry/ulises-jeremias-agent-toolkit-swarm-observer/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.