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

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

name	description	version	author	license	platforms	environments	metadata
tmux-agent-orchestrate-stop	Stop an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml. Hard mode marks status=terminated; stop options (--capture-id/--reason/--graceful) mark status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start.	1.0.0	godopu	MIT	linux macos	terminal tmux	hermes tags related_skills prereq_skills agent tmux claude antigravity agy multi-agent stop terminate cleanup tmux-agent-orchestrate-create tmux-agent-orchestrate-resume tmux-agent-orchestrate-monitor tmux-agent-orchestrate-create tmux-agent-orchestrate-resume

Multi-Agent Stop — Stop an Agent tmux Session

Companion skills: tmux-agent-orchestrate-create (start), tmux-agent-orchestrate-resume (re-attach), tmux-agent-orchestrate-monitor (live status). Tmux Isolation: stop 명령은 YAML의 tmux_server 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, TMUX_SERVER_NAME 환경변수를 수동으로 지정할 필요가 없습니다. Single source of truth: ./.hermes/agent-sessions.yaml.

What this skill does

Stop an agent's tmux session and mark the YAML entry (terminated or stopped). Preserves:

• The tmux session's recorded pane.pid / cmd / cwd / mcp_attachments for audit
• The agent's on-disk conversation (claude *.jsonl, agy conversations/*.db) — so the user can tmux-agent-orchestrate-resume later
• The start_command so a future tmux-agent-orchestrate-create --session <name> reproduces the same tmux spec

The user explicitly chooses:

• soft stop (default): update YAML only; leave tmux running. Useful when "stop" really means "I'm done with this card".
• hard stop: tmux kill-session + update YAML. The default when the user says "kill it" or "end the session".

Pre-flight

SESSION_NAME=<workspace>-creator-<agent>  # convention
AGENT_SESSIONS_YAML=.hermes/agent-sessions.yaml

# 1) Session is registered?
python3 -c "
import yaml
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
names = [s['name'] for s in d.get('tmux_sessions', [])]
if '$SESSION_NAME' not in names:
    print('NOT in YAML — refusing to stop (no audit trail). Use tmux-agent-orchestrate-create first, or pass --force-no-yaml.')
    raise SystemExit(1)
"

# 2) Already terminated?
ALREADY=$(python3 -c "
import yaml
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
print(s.get('status', 'unknown'))
")
if [ "$ALREADY" = "terminated" ]; then
  echo "Already terminated at $(python3 -c "import yaml; d=yaml.safe_load(open('$AGENT_SESSIONS_YAML')); print([x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0].get('terminated_at',''))")"
  echo "Re-running will just refresh the timestamp. Continue? (--yes to skip)"
fi

Workflow

# 1. soft stop (YAML only — tmux left running)
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --mode soft

# 2. hard stop (default — kill tmux + update YAML)
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --mode hard

# 3. hard stop + clean up on-disk conversation (DANGEROUS)
#    — this prevents any future resume. Use only when user is certain.
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --mode hard --purge-conversation

Stop extension (Option A — stop semantics without a 6th skill)

Rather than a separate tmux-agent-orchestrate-stop route, the base stop command absorbs the "stop" intent via three opt-in options. Passing any of them switches the YAML transition from terminated to stopped (running → stopped), signalling "deliberately stopped, conversation preserved, ready to resume":

# Stop: capture the conversation id into the row, record a reason, exit gracefully.
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --capture-id --reason api_error --graceful

Option	Effect
--capture-id	Before kill, resolve THIS workspace's conversation id via find_workspace_uuid (per-row → workspace-scoped disk scan → cache) and record it to claude_session_id_own / agy_conversation_id_own, plus resumable: true. Guarantees the next resume hits tier-1 (race-free) instead of the mtime-based disk-scan fallback.
--reason <reason>	Records stop_reason (default manual_stop). Convention: user_request / api_error / timeout / crash / manual_stop.
--graceful	tmux send-keys exit (/exit for claude, Exit for agy) → 3 s wait → if alive tmux kill-session (SIGTERM) → 5 s → kill -9 pane pid as last resort. Avoids hard-killing a TUI mid-write.

Idempotency: in STOP mode, if the row is already status: stopped, the script prints already stopped (...) and exits 0 — re-running is a safe no-op.

Backward compatibility: with none of these options, the base stop command behaves exactly as before (hard→terminated, soft→archived).

State machine

running ──(stop --mode hard)────────────────► terminated
running ──(stop --capture-id/--reason/--graceful)► stopped   (resumable, conv preserved)
running ──(stop --mode soft)────────────────► archived      (tmux left alive)
stopped ──(stop --capture-id … again)───────► stopped       (idempotent no-op)
any     ──(stop --purge-conversation --yes)─► (conv deleted, resumable:false)

Fields written in STOP mode: status: stopped, stopped_at, stopped_at_epoch, stop_reason, termination_mode: stop|graceful, and (with --capture-id) claude_session_id_own/agy_conversation_id_own + resumable: true.

The script:

1. Verifies the session is in agent-sessions.yaml
2. If delegate_job_id is set, automatically publishes a progress --detail "terminating" event to the tmux-agent-orchestrate-delegate-job registry
3. Captures the last_visible_status from tmux capture-pane (so we have a final TUI snapshot for audit)
4. For hard mode: tmux kill-session -t <name> (which auto-SIGTERMs children including the agent)
5. For purge-conversation: deletes ~/.claude/projects/.../jsonl (claude) or ~/.gemini/antigravity-cli/conversations/...db + brain/... (agy)
6. Updates the YAML entry
7. If delegate_job_id is set, publishes a completed event to the tmux-agent-orchestrate-delegate-job registry
8. Updates the YAML entry:

   - name: <SESSION_NAME>
     status: terminated
     terminated_at: 2026-06-17T...Z
     terminated_at_epoch: ...
     # all original fields preserved
   

Pitfalls

• tmux kill-session doesn't just kill the session — it sends SIGHUP to the pane's child processes too. This is usually what you want (the agent process dies, no zombie reparenting to init). But if you wanted to keep the agent running outside tmux for some reason, use soft mode.
• Don't delete on-disk artifacts by default — the agent's *.jsonl / conversations/*.db is the data that tmux-agent-orchestrate-resume needs. --purge-conversation is for when the user is genuinely done with the conversation and wants zero recovery chance.
• YAML is append-only until you write a stop — if a previous run left the entry as running but tmux is actually dead (crash, host reboot), the YAML is stale. Running tmux-agent-orchestrate-stop --mode hard will detect "tmux already dead, just update YAML" and proceed.
• Don't delete the claude_session_id_own: null placeholder — when the user creates a fresh session with tmux-agent-orchestrate-create and never sent a message, the entry has claude_session_id_own: null. Stopping must preserve that field (it's the audit trail showing "this tmux session never produced a session id of its own").
• Monitor skill may still be tracking — if tmux-agent-orchestrate-monitor is running a heartbeat loop, stopping a session while it watches will trigger its tmux ls != yaml reconciliation. That's expected — let the monitor run, it will mark the entry as terminated on its own. Don't fight it.

Verification

# 1. tmux gone
tmux has-session -t "$SESSION_NAME" 2>/dev/null && echo "STILL ALIVE" || echo "OK: tmux gone"

# 2. YAML has terminated entry
python3 -c "
import yaml
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
assert s['status'] == 'terminated', f'expected terminated, got {s[\"status\"]}'
assert s.get('terminated_at'), 'missing terminated_at'
print(f'OK: terminated at {s[\"terminated_at\"]}')
print(f'  preserved: pane.pid={s[\"pane\"][\"pid\"]}, cmd={s[\"pane\"][\"cmd\"]}, cwd={s[\"pane\"][\"cwd\"]}')
"

# 3. (if --purge-conversation) disk artifacts gone (CLAUDE_PROJECT_DIR env var overrides default $HOME/.claude/projects)
[ -f "${CLAUDE_PROJECT_DIR:-$HOME/.claude/projects}/<projkey>/<uuid>.jsonl" ] && echo "WARN: jsonl still exists" || echo "OK: jsonl purged"

When NOT to use this skill

• Just detaching → tmux detach (Ctrl-B d) or just close the terminal. The tmux session keeps running.
• Stopping the agent inside but keeping tmux → send Ctrl-C or /exit (claude) / Ctrl-D (agy) via tmux send-keys. The tmux session stays but the agent process is gone; you can then tmux-agent-orchestrate-create again to spawn a fresh agent in the same tmux session.
• Replacing an existing session with a new one → tmux-agent-orchestrate-stop --mode hard first, then tmux-agent-orchestrate-create.