multi-agent-mux/skills/tmux-agent-orchestrate-status/SKILL.md

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

name	description	version	author	license	platforms	environments	metadata
tmux-agent-orchestrate-status	Read-only instant snapshot of all agent tmux sessions — name, YAML status, tmux alive, pane cmd/cwd, resume UUID on disk, and any drift. No Kanban, 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 a Kanban monitor worker.	1.0.0	godopu	MIT	linux macos	terminal tmux	hermes tags related_skills prereq_skills agent tmux claude antigravity agy status read-only snapshot tmux-agent-orchestrate-create tmux-agent-orchestrate-resume tmux-agent-orchestrate-delete tmux-agent-orchestrate-monitor tmux-agent-orchestrate-create tmux-agent-orchestrate-monitor

Multi-Agent Status — Read-Only Instant Snapshot

Companion skills: tmux-agent-orchestrate-create (start), tmux-agent-orchestrate-resume (re-attach), tmux-agent-orchestrate-delete (terminate), tmux-agent-orchestrate-monitor (live polling). Tmux Isolation: status 명령은 YAML에 등록된 모든 세션의 격리 서버(tmux_server 필드)를 자동으로 조회하여 상태를 확인하므로, TMUX_SERVER_NAME 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다. Single source of truth: ~/PuKi/lab/agent_sessions/agent-sessions.yaml.

What this skill does

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

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

Pre-flight

command -v tmux
command -v python3
test -f ~/PuKi/lab/agent_sessions/agent-sessions.yaml

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

Workflow

bash ~/PuKi/lab/agent_sessions/skills/tmux-agent-orchestrate-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 tmux_sessions[]:
   • tmux alive? (via tmux has-session -t <name>)
   • pane cmd, cwd (via tmux list-panes)
   • resume UUID on disk? (claude: ~/.claude/projects/<key>/<uuid>.jsonl; agy: ~/.gemini/antigravity-cli/conversations/<uuid>.db)
4. For each tmux 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  (tmux_confirmed=True)
========================================================================================================================================
NAME                                         SERVER       YAML       TMUX   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": "...",
  "tmux_sessions_alive": ["..."],
  "yaml_entries": [...],
  "rows": [
    {
      "name": "lab-landing-page-creator-claude",
      "yaml_status": "running",
      "tmux_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",
      "tmux_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, tmux dead	session died without going through tmux-agent-orchestrate-delete. Could auto-terminate but won't — that's tmux-agent-orchestrate-monitor's job.
B	tmux alive, not in YAML	ad-hoc session someone started without tmux-agent-orchestrate-create. Suggest: "use tmux-agent-orchestrate-create to register, or tmux kill-session to clean up."
C	YAML has claude_session_id_own: null AND a new *.jsonl exists	new session id materialized; suggest: "run tmux-agent-orchestrate-resume or reconcile to register it."
D	YAML has UUID in agent_identities, but the on-disk artifact is gone	stale UUID; user should tmux-agent-orchestrate-delete --purge-conversation to clean up.

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, dispatch tmux-agent-orchestrate-monitor (Kanban worker) or run tmux-agent-orchestrate-resume / tmux-agent-orchestrate-delete manually.
• Read-only is enforced by script — status.sh opens the YAML with open(path) (no 'w'), never calls tmux 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 tmux-agent-orchestrate-delete --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 tmux-agent-orchestrate-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 Kanban task

When NOT to use

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