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. Default stops gracefully and marks 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 gracefully, resolve and store the conversation ID, and mark the YAML entry (status=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 stop command is always graceful by default:

1. Sends exit keys to the agent TUI (/exit for Claude, Exit for Agy) and waits 3 seconds.
2. If still alive, issues tmux kill-session (SIGTERM) and waits 5 seconds.
3. If still alive, kills the pane PID via SIGKILL (kill -9) as a last resort.
4. Auto-captures the conversation ID into the row (claude_session_id_own/agy_conversation_id_own) before killing, ensuring the next resume uses a race-free tier-1 lookup.

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 stopped?
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" = "stopped" ]; then
  echo "Already stopped."
fi

Workflow

# 1. Stop gracefully (default — captures ID, shuts down safely, status=stopped)
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME"

# 2. Stop gracefully + record a custom stop reason
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --reason api_error

# 3. Stop gracefully + clean up on-disk conversation (DANGEROUS)
#    — this prevents any future resume (status=terminated, resumable=false).
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --purge-conversation

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

State machine

running ──(stop default / --reason)────────► stopped      (resumable:true, conv preserved)
running ──(stop --purge-conversation --yes)► terminated   (resumable:false, conv deleted)
stopped ──(stop default … again)───────────► stopped      (idempotent no-op)

Fields written in STOP mode: status: stopped, stopped_at, stopped_at_epoch, stop_reason, termination_mode: graceful, claude_session_id_own/agy_conversation_id_own and resumable: true.

If --purge-conversation is used: status: terminated, terminated_at, terminated_at_epoch, termination_mode: purge and resumable: false.

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. Attempts graceful exit keys → SIGTERM kill-session → SIGKILL fallback
5. For purge-conversation: deletes ~/.claude/projects/.../jsonl (claude) or ~/.gemini/antigravity-cli/conversations/...db + brain/... (agy)
6. Updates the YAML entry and SQLite database atomically
7. If delegate_job_id is set, publishes a completed event to the tmux-agent-orchestrate-delegate-job registry

Pitfalls

• 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 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.
• 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.

Verification

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

# 2. YAML has stopped 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'] == 'stopped', f'expected stopped, got {s[\"status\"]}'
assert s.get('stopped_at'), 'missing stopped_at'
print(f'OK: stopped at {s[\"stopped_at\"]}')
print(f'  preserved: pane.pid={s[\"pane\"][\"pid\"]}, cmd={s[\"pane\"][\"cmd\"]}, cwd={s[\"pane\"][\"cwd\"]}')
"

# 3. (if --purge-conversation) disk artifacts gone
[ -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.
• Replacing an existing session with a new one → tmux-agent-orchestrate-stop first, then tmux-agent-orchestrate-create.