Agent-Skills.md

Agent Skills: cmux Resume Sessions

>

UncategorizedID: devseunggwan/skills/cmux-resume-sessions

Repository

devseunggwan/skills
devseunggwanLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/devseunggwan/praxis/tree/HEAD/skills/cmux-resume-sessions

Skill Files

Browse the full folder contents for cmux-resume-sessions.

Download Skill

Loading file tree…

skills/cmux-resume-sessions/SKILL.md

Skill Metadata

Name
cmux-resume-sessions
Description
>

cmux Resume Sessions

⚠️ Wrong skill? If your sessions died from a crash / power loss / OOM kill, use cmux-recover-sessions instead. That skill scans .jsonl files on disk and finds sessions you never explicitly saved. Resume only works on a JSON snapshot you produced earlier with cmux-save-sessions.

Overview

Restores cmux workspaces from a JSON snapshot saved by cmux-save-sessions. Restores workspace structure (name, cwd) and continues Claude Code conversations automatically.

Role separation:

  • cmux-resume-sessions (this skill): Intentional restore from a JSON snapshot you saved on purpose (file-based)
  • cmux-recover-sessions: Post-crash/power-loss recovery from .jsonl files Claude Code persists automatically (process-based)

The Iron Law

RESUME RESTORES STRUCTURE AND CONTINUES CONVERSATIONS.

Resume restores workspace structure (name, cwd) and, per session, runs claude --resume <session-id> when the snapshot carries a session id — falling back to claude --continue (the cwd's most recent conversation) when it does not — to pick up the prior conversation in each directory. It does NOT restore runtime state of previously running commands or sessions.

When to Use

  • Restore a workspace layout from a cmux-save-sessions snapshot
  • Rehydrate yesterday's working set at the start of a new day
  • Move a session layout to another machine (snapshot → transfer → resume)

Not for crash recovery — after a power loss, use cmux-recover-sessions (scans .jsonl files directly).

Commands

resume [snapshot] — Restore sessions from snapshot

How to run:

  1. User requests "resume sessions", "session restore", etc.
  2. Snapshot resolution — resolve snapshot to a full path before the gate, mirroring the CLI's logic at cmux-resume-sessions lines 5-13, 23-30 so the gate sees the same file the CLI will open. Mirror the CLI parser exactly: consume --no-claude (the only recognized flag), and treat every other token — including unknown --flag strings — as a positional candidate, taking the first one as the snapshot candidate:
SAVE_DIR="$HOME/.cmux/sessions"
arg=""
for a in "$@"; do
  case "$a" in
    --no-claude) ;;  # only recognized flag — skip (mirror of CLI line 10)
    *) arg="$a"; break ;;  # every other token, including unknown --flag, is positional (mirror of CLI line 11)
  esac
done
# arg is now "" (no positional) or a bare filename / full path / a literal "--flag" the CLI would also pass through
if [[ -z "$arg" ]]; then
  snapshot=$(ls -t "$SAVE_DIR"/sessions-*.json | head -1)
elif [[ -f "$arg" ]]; then
  snapshot="$arg"
elif [[ -f "$SAVE_DIR/$arg" ]]; then
  snapshot="$SAVE_DIR/$arg"
else
  echo "ERROR: snapshot '$arg' not found in cwd or $SAVE_DIR" >&2; exit 1
fi
  1. Hostname mismatch gate — verify the snapshot's saved host matches the current machine before restoring:
saved_host=$(jq -r '.hostname // empty' "$snapshot")
current_host=$(hostname)
  • If ${saved_host} is empty (legacy snapshot without the field): proceed silently.
  • If ${saved_host} equals ${current_host}: proceed silently.
  • If ${saved_host} differs from ${current_host}: surface AskUserQuestion:
    • Question: "이 스냅샷은 다른 머신 (${saved_host}) 에서 저장되었습니다. 현재 머신은 ${current_host} 입니다. cwd 경로가 맞지 않을 수 있어 세션 다수가 'cwd not found' 로 스킵될 수 있습니다. 계속할까요?"
    • Options: "계속 진행" / "취소"
  • If user selects "취소": abort with "Resume 취소됨 — 호스트 불일치 (${saved_host} → ${current_host})."
  1. Execute (only after the hostname gate passes). Pass through all original args ("$@") so flags like --no-claude survive:
bash "$(dirname "$0")/cmux-resume-sessions" "$@"
  1. Show output to the user

What gets restored:

  • Creates a cmux workspace per session (with --cwd for working directory)
  • Sets workspace name to match the saved name
  • Runs claude --resume <session-id> if session ID is available, otherwise claude --continue (continues the most recent conversation for that cwd)
  • Sessions with non-existent cwd are skipped (with warning)
  • Duplicate workspaces (same name already exists) are skipped automatically

Flags:

  • --no-claude: Skip auto-starting Claude Code (restore workspace structure only)

What is NOT restored:

  • Previously running commands
  • Session runtime state (git status, open editors, etc.)

⚠️ Resumed sessions render from the first message. Claude Code re-renders a resumed conversation starting at the oldest message, so a workspace will look like it reverted to its earliest state.

Which command fires for each workspace depends on what the snapshot captured:

  • claude --resume <session-id> — used when the snapshot carries a concrete session id. This usually reopens that exact transcript, but it is not a guarantee (stale session id, partial flush at save time, or a truncated tail can all surface as unexpected context).
  • claude --continue — the fallback when the snapshot omitted a session id. This attaches to the cwd's most recent conversation for that working directory, which may be a completely different chain from the one you saved. See the Rationalization Prevention section at the bottom for the exact failure mode.

Always verify each restored workspace before trusting it:

  • scroll the viewport to the bottom, or
  • ask the model directly: "what was the last thing we worked on?"

Output Example

Resuming from: sessions-20260407-143000.json
  Saved at: 2026-04-07T14:30:00+0900 | Host: macbook-pro.local | Sessions: 7

  ✓ Review PR comments → workspace:150 (/Users/nathan.song/projects/hub)
  ✓ Fix auth bug → workspace:151 (/Users/nathan.song/projects/backend)
  ⚠ SKIP: Old worktree task (cwd not found: /tmp/wt-deleted)
  ✗ FAIL: Broken session

Done. Created: 2 | Skipped: 1 | Failed: 1

Integration

  • cmux-save-sessions: Produces the input data for this skill
  • cmux-session-manager: Use status to verify results after restore

Troubleshooting

| Problem | Cause | Fix | | --------- | ------- | ----- | | "cmux is not running" | cmux app not running | Start cmux app | | "jq is required" | jq not installed | brew install jq | | "cwd not found" | Directory was deleted since save | Session is auto-skipped | | "No snapshots" | No saved snapshots exist | Save first with cmux-save-sessions | | Duplicate sessions created | Overlap with already-open sessions | Check existing sessions before restore |

Rationalization Prevention

| Excuse | Reality | | -------- | --------- | | "Restore every snapshot at once" | Old snapshots point to cwd paths that no longer exist. Restore the most recent that's still valid. | | "Skip --no-claude, always auto-start Claude" | If the target cwd's recent conversation is stale, auto-continue lands in the wrong context. Use --no-claude when in doubt. | | "Ignore duplicate warnings" | Duplicate workspaces are noise at best, collision at worst. Inspect existing sessions first. | | "Restore before verifying the snapshot's host" | Cross-machine restore may succeed with stale paths. The hostname mismatch gate (Step 3 in resume "How to run") surfaces an AskUserQuestion when jq -r '.hostname' differs from $(hostname) — do not click through without inspecting the cwd paths. |