multi-agent-mux/.agents/skills/multi-agent-mux-status/SKILL.md

name, description, version, author, license, platforms, environments, metadata

name	description	version	author	license	platforms	environments	metadata
multi-agent-mux-status	Read-only instant snapshot of all agent herdr sessions — name, YAML status, herdr alive, pane cmd/cwd, resume UUID on disk, and any drift. No mutation. Reuses reconcile.sh --dry-run for the diff logic. Use when you want to know 'what's running RIGHT NOW' without spinning up the monitor loop.	2.0.0	godopu	MIT	linux macos	terminal herdr	hermes tags related_skills prereq_skills agent herdr claude antigravity agy status read-only snapshot multi-agent-mux-create multi-agent-mux-resume multi-agent-mux-stop multi-agent-mux-monitor multi-agent-mux-create multi-agent-mux-monitor

Multi-Agent Status — Read-Only Instant Snapshot

Companion skills: multi-agent-mux-create (start), multi-agent-mux-resume (re-attach), multi-agent-mux-stop (terminate), multi-agent-mux-monitor (live polling). Herdr Isolation: status 명령은 YAML의 herdr_session 필드를 자동으로 파싱하여 상태를 확인하므로, HERDR_SESSION_NAME 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다. Single source of truth: ./.mam/agent-sessions.yaml.

What this skill does

Print a single table of every agent herdr session, comparing YAML state to actual herdr state. No mutation. No polling loop.

This is the "what's running right now?" answer — faster than dispatching multi-agent-mux-monitor (which polls every 30s) and safer than reconcile.sh --once --emit-diff (which mutates as a side effect).

Pre-flight

has_real_herdr || { echo "ERROR: herdr not installed"; exit 1; }   # lib.sh helper (B-3)
command -v python3
test -f .mam/agent-sessions.yaml

command -v herdr and type -P herdr both report success even when herdr is not installed — they match lib.sh's herdr() function and the .mam/shim wrapper respectively. Always use has_real_herdr.

If agent-sessions.yaml doesn't exist or is malformed → print clear error, exit 1. Do not create it. (Use multi-agent-mux-create first.)

Workflow

bash .agents/skills/multi-agent-mux-status/scripts/status.sh [--json]

The script:

1. Calls reconcile.sh --once --emit-diff --dry-run (read-only; no YAML mutation) for the drift snapshot
2. Loads agent-sessions.yaml (read-only) to enrich the table
3. For each row in herdr_sessions[]:
   • herdr alive? (via herdr agent get <name>, real native command — the script sources lib.sh internally, which is what lets it also spell this as herdr has-session -t <name>)
   • pane cmd, cwd (via herdr agent get <name>, likewise shimmed as herdr list-panes internally)
   • resume UUID on disk? (claude: $CLAUDE_PROJECT_DIR/<key>/<uuid>.jsonl with default ~/.claude/projects/; agy: $HOME_DIR/.gemini/antigravity-cli/conversations/<uuid>.db with default ~/.gemini/...)
4. For each herdr session matching *-creator-* not in YAML → flag as "unregistered"
5. Prints a table (default) or JSON (with --json)

Output format (default = aligned table)

agent-sessions status — 2026-06-19T14:20:00Z  (herdr_confirmed=True)
========================================================================================================================================
NAME                                         SERVER       YAML       HERDR   CMD    RESUME   JOB_ID    JOB_STATUS   DRIFT
----------------------------------------------------------------------------------------------------------------------------------------
lab-landing-page-creator-claude              default      running    alive  claude yes      -         -            -
lab-landing-page-creator-agy                 default      terminated dead   agy    yes      5fe09ba8  completed    -
lab-paper-pdf2md-creator-claude              default      running    alive  claude scan     -         -            -
========================================================================================================================================

Output format (--json)

{
  "yaml_path": "...",
  "herdr_sessions_alive": ["..."],
  "yaml_entries": [...],
  "rows": [
    {
      "name": "lab-landing-page-creator-claude",
      "yaml_status": "running",
      "herdr_alive": true,
      "pane_cmd": "claude",
      "pane_cwd": "/home/.../refer_landing_page",
      "resume_uuid_on_disk": true,
      "drift": null
    },
    {
      "name": "lab-landing-page-creator-agy",
      "yaml_status": "terminated",
      "herdr_alive": false,
      "drift": "yaml-says-terminated-but-disk-uuid-still-present"
    }
  ],
  "unregistered": [],
  "drifts": []
}

Drift classes (read-only — never mutates)

Class	Detection	Meaning
A	YAML running, herdr dead	session died without going through multi-agent-mux-stop. Could auto-terminate but won't — that's multi-agent-mux-monitor's job.
B	herdr alive, not in YAML	ad-hoc session someone started without multi-agent-mux-create. Suggest: "use multi-agent-mux-create to register, or multi-agent-mux-stop to clean up."
C	YAML has claude_session_id_own: null AND a new *.jsonl exists	new session id materialized; suggest: "run multi-agent-mux-resume or reconcile to register it."

Pitfalls

• Do NOT use this skill to drive mutations — the output is a snapshot, not a call to action. If you need to fix drifts, run multi-agent-mux-monitor or multi-agent-mux-resume / multi-agent-mux-stop manually.
• Read-only is enforced by script — status.sh opens the YAML with open(path) (no 'w'), never calls herdr kill-session, never writes anywhere. The reconcile.sh --dry-run mode is the same path.
• If agent-sessions.yaml is malformed — print the YAML error verbatim and exit 1. Do NOT attempt recovery (that's multi-agent-mux-stop --purge-conversation or manual edit's job).
• Sessions outside the <workspace>-creator-* naming convention are still shown but tagged ad-hoc — they didn't go through multi-agent-mux-create and aren't tracked in YAML.

When to use

• "Is the claude session still running?" → this skill, not the monitor
• "What UUID does this workspace have?" → this skill
• "Is there drift between YAML and reality?" → this skill, then dispatch monitor or fix manually
• Quick sanity check before dispatching a long-running job

When NOT to use

• Continuous live tracking → multi-agent-mux-monitor
• Recovering from corruption → manual edit + .bak restore
• Polling more than once a minute → multi-agent-mux-monitor (it dedupes)