cmux-claude-resume

cmux-claude-resume

cmux restores window layout, workspaces, and per-pane cwd after relaunch — but it does not restore the process running in each pane. After a reboot, panes come back empty: you lose the claude process and its session context, even though Claude Code itself keeps the session on disk and can be resumed.

This skill closes that gap by adding two pieces:

1. A Claude Code SessionStart hook that records cwd → session_id to a small JSON state file.
2. A launchd watcher that detects cmux coming up and types claude --resume <session_id> into every restored terminal pane whose cwd is known.

Restore is anchored by directory, not by cmux pane UUID — robust to UUID churn and matches the one-worktree-per-directory mental model.

Install

# Install everything (scripts → ~/.local/bin, hook → ~/.claude/settings.json,
# LaunchAgent → ~/Library/LaunchAgents)
bash "$(dirname "$0")/install.sh"

Re-run the installer at any time — it is idempotent.

Verify

# 1. Confirm the Claude hook is wired.
jq '.hooks.SessionStart' ~/.claude/settings.json

# 2. After opening a Claude Code session inside a cmux pane,
#    confirm the state file got updated.
cat ~/.local/share/cmux-claude-resume/state.json

# 3. Preview what the restorer would do without sending anything.
cmux-claude-restore --dry-run

Uninstall

bash "$(dirname "$0")/uninstall.sh"

State file is preserved on uninstall — delete ~/.local/share/cmux-claude-resume/state.json manually if you want a clean slate.

Files

File	Path	Purpose
cmux-claude-record	~/.local/bin/	Claude SessionStart hook handler
cmux-claude-restore	~/.local/bin/	One-shot restorer (run by watcher or manually)
cmux-claude-resume-watcher	~/.local/bin/	Polls for cmux up-transitions and fires the restorer
com.mjmendo.cmux-claude-resume.plist	~/Library/LaunchAgents/	Keeps watcher running across login sessions
state	~/.local/share/cmux-claude-resume/state.json	cwd → {session_id, ts} mapping
logs	~/Library/Logs/cmux-claude-resume.log	Watcher & restore output

When it does and doesn't fire

• ✅ Fires for any cmux terminal pane whose cwd has a recorded session_id.
• ✅ Safe to run multiple times — the restorer skips panes that already show a Claude prompt (heuristic on read-screen).
• ⚠️ If two panes share the same cwd, only the first one gets resumed. Open a worktree-per-pane for clean 1:1.
• ❌ Will not restart Claude in a pane that's still running something else (e.g. you left htop open).
• ❌ Does not snapshot in-flight unsaved tool output — Claude's own session log is the source of truth.

Troubleshooting

# Tail the watcher log
tail -f ~/Library/Logs/cmux-claude-resume.log

# Re-load the LaunchAgent (after install changes)
launchctl unload ~/Library/LaunchAgents/com.mjmendo.cmux-claude-resume.plist
launchctl load   ~/Library/LaunchAgents/com.mjmendo.cmux-claude-resume.plist

# See where Claude's session files live (so you know what's being resumed)
ls ~/.claude/projects/