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

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

name	description	version	author	license	platforms	environments	metadata
tmux-agent-orchestrate-resume	Resume an existing agent (claude, antigravity/agy) conversation by UUID into a tmux session. Reads .hermes/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a tmux session of the matching name, and runs `claude -r <id>` or `agy --conversation <id>` inside. Use when you want to reattach to a previous session's context, or revive a session whose tmux died but the agent's conversation is still on disk.	1.0.0	godopu	MIT	linux macos	terminal tmux	hermes tags related_skills prereq_skills agent tmux claude antigravity agy multi-agent context resume session-id tmux-agent-orchestrate-create tmux-agent-orchestrate-delete tmux-agent-orchestrate-monitor claude-code tmux-agent-orchestrate-create

Multi-Agent Resume — Reattach to a Saved Conversation

Companion skills: tmux-agent-orchestrate-create (start a fresh agent), tmux-agent-orchestrate-delete (terminate), tmux-agent-orchestrate-monitor (live status). Tmux Isolation: TMUX_SERVER_NAME env var를 create에서 설정한 경우, 동일 서버에서 동작합니다. 자세한 격리 패턴은 tmux-agent-orchestrate-create/SKILL.md 참조. Single source of truth: ./.hermes/agent-sessions.yaml.

What this skill does

Container + data reconstruction: spawn a tmux session (the container), then run the agent inside with a specific session id (the data) so the previous conversation's context is restored.

Three cases this skill handles:

1. tmux is dead, conversation lives — agent-sessions.yaml has the UUID. The JSONL/db is on disk. Re-spawn the tmux session + run claude -r <id> / agy --conversation <id>.
2. tmux is alive but empty — You started a session with tmux-agent-orchestrate-create but haven't sent a message yet (so no session id was assigned). The user can either send their first message (and the id is auto-assigned), or you can read the workspace's most recent conversation from $HOME_DIR/.gemini/antigravity-cli/cache/last_conversations.json (defaults to ~/.gemini/...) for agy, or the latest *.jsonl in $CLAUDE_PROJECT_DIR/<workspace-key>/ (defaults to ~/.claude/projects/) for claude.
3. tmux is alive AND the agent inside is already running — Just attach. No re-spawn needed.

UUID resolution order

agent-sessions.yaml is the primary source. The skill reads in this order:

1. agent-sessions.yaml → agent_identities.<agent>.session_id (claude) / conversation_id (agy) — explicit saved value
2. agent-sessions.yaml → agent_identities.<agent>.session_jsonl (claude) / conversation_db (agy) — the on-disk artifact
3. Fallback: scan disk for the workspace's most recent conversation (Note: CLAUDE_PROJECT_DIR overrides the default ~/.claude/projects/ path, and HOME_DIR overrides the ~ path) —
   • claude: ls -t $CLAUDE_PROJECT_DIR/<workspace-key>/*.jsonl | head -1 and parse the sessionId from the first line
   • agy: jq -r '."<workspace>"' $HOME_DIR/.gemini/antigravity-cli/cache/last_conversations.json

If all three are empty → the workspace has no conversation yet. Fall back to tmux-agent-orchestrate-create.

Workflow

WORKSPACE=/path/to/project
AGENT=claude  # or agy
SESSION_NAME=<workspace>-creator-<agent>  # same convention as tmux-agent-orchestrate-create

# 1. Resolve the session id
UUID=$(bash skills/tmux-agent-orchestrate-resume/scripts/resolve_session_id.sh \
  --workspace "$WORKSPACE" --agent "$AGENT")

if [ -z "$UUID" ]; then
  echo "No saved session for $WORKSPACE ($AGENT). Use tmux-agent-orchestrate-create first."
  exit 1
fi

# Resolve the isolated tmux server name
source skills/lib.sh
export TMUX_SERVER_NAME="$(resolve_tmux_server "$SESSION_NAME")"

# 2. If tmux is alive, attach. Done.
if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
  echo "tmux '$SESSION_NAME' already running. Attaching..."
  exec tmux attach -t "$SESSION_NAME"
fi

# 3. Spawn new tmux session + run agent with the saved id
case "$AGENT" in
  claude)
    tmux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
      "claude --dangerously-skip-permissions -r $UUID"
    # auto-handle trust / bypass dialogs
    sleep 5
    tmux send-keys -t "$SESSION_NAME" Enter 2>/dev/null || true
    sleep 3
    tmux send-keys -t "$SESSION_NAME" Down 2>/dev/null || true
    sleep 0.3
    tmux send-keys -t "$SESSION_NAME" Enter 2>/dev/null || true
    ;;
  agy)
    tmux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
      "agy --dangerously-skip-permissions --conversation $UUID"
    ;;
esac

# 4. Update agent-sessions.yaml: status running, last_visible_status
# (Also automatically publishes a `progress --detail "resumed"` event to the tmux-agent-orchestrate-delegate-job registry if a delegate_job_id exists)
bash skills/tmux-agent-orchestrate-resume/scripts/update_yaml_resumed.sh \
  --session "$SESSION_NAME" --uuid "$UUID"

# 5. Attach
tmux attach -t "$SESSION_NAME"

Pitfalls

• claude -r requires the SAME project directory — if the workspace path differs from when the session was created, claude will create a new project dir key (-home-...-different-name) and put the resume in a different location. Always -c (cd to workspace) before running.
• agy's --conversation flag name varies by version — older versions used --resume or -r. Check agy --help | grep -E "conversation|resume" and use the right flag. v1.0.x: --conversation.
• The first message after resume might re-trigger TUI dialogs — if the original session was created with --dangerously-skip-permissions, those flags are NOT persisted; you must re-apply them on resume. The script above re-passes them.
• Don't resume if the session is brand new and empty — tmux-agent-orchestrate-create already set up an empty container; sending a probe message ("init") is the right way to materialize a session id, NOT claude -r with a placeholder.
• agy --conversation <id> will fail if the conversation was deleted from disk — check ~/.gemini/antigravity-cli/conversations/<uuid>.db exists before attempting resume. If missing, the conversation is gone; you need a fresh session via tmux-agent-orchestrate-create.

Verification

# 1. tmux alive with the right cmd
tmux list-panes -t "$SESSION_NAME" -F 'cmd=#{pane_current_command} cwd=#{pane_current_path}'

# 2. agent-sessions.yaml updated
python3 -c "
import yaml
d = yaml.safe_load(open('.hermes/agent-sessions.yaml'))
s = [s for s in d['tmux_sessions'] if s['name'] == '$SESSION_NAME'][0]
print(f'  status: {s[\"status\"]}')
print(f'  pane.cmd_full: {s[\"pane\"][\"cmd_full\"]}')
"

# 3. TUI shows resumed conversation (capture-pane to verify)
sleep 5
tmux capture-pane -t "$SESSION_NAME" -p -S -30
# look for the previous message at top of the buffer (claude) or last_visible_status set (agy)

When NOT to use this skill

• No saved session yet → tmux-agent-orchestrate-create
• Killing an existing session → tmux-agent-orchestrate-delete
• Just attaching → tmux attach -t <name> (no skill needed)