If you run several Claude Code sessions in tmux, a reboot costs you more than your layout. tmux-resurrect brings back your sessions, windows, panes, folders and scrollback, but every pane that was running Claude comes back as an empty shell. You then have to work out which conversation lived where. The fix is two small hook scripts. One records which Claude conversation each pane was running on every save. The other relaunches each pane with claude --resume on every restore, one pane at a time.

This post walks through the setup we run on our own workstation: the plugins, the config, both hooks in full, how to test it without touching your live tmux, and the problems we hit along the way.

15 min
Autosave interval (continuum)
1 pane / 7 s
Staggered relaunch
2
Hook scripts (~200 lines total)
0
Secrets stored in the session map

The problem: tmux-resurrect restores panes, not conversations

tmux-resurrect saves a snapshot of your tmux server: sessions, windows, pane layouts, each pane's working directory and, if you enable it, its scrollback. It can also restart a short list of programs, such as vim or htop, when you restore.

That list is the catch. If you add claude to it, resurrect restarts a fresh Claude in each pane, with none of the earlier context. It also starts every one of them at the same instant, which on a box with a dozen panes means a burst of memory use and API calls all at once.

What we actually want on restore is this: this pane gets back the conversation it was having. Two panes in the same project folder hold two different conversations, so "resume the latest conversation in this folder" isn't enough.

How the setup works

There are four layers. The first three are standard tmux plugins; the fourth is the glue.

LayerJob
tpmPlugin manager: installs and loads the others
tmux-resurrectSaves and restores sessions, windows, panes, folders and scrollback
tmux-continuumSaves automatically every 15 minutes and restores when the tmux server starts
Two hooksSave: map each pane to its Claude session ID. Restore: relaunch each pane with claude --resume

On every save (continuum's timer or prefix + Ctrl-s), resurrect writes its snapshot and then runs the post-save hook. The hook lists every pane whose current command is claude and walks from the pane's shell process down to the claude process. It then reads Claude Code's per-process registry file, ~/.claude/sessions/.json, to get that process's sessionId and working directory. It writes one line per pane to claude-sessions.map next to the snapshot:

work:1.1	3f2a9c4e-…	/home/you/projects/api
work:2.1	8be410d2-…	/home/you/projects/web
work:2.2	c71d05aa-…	/home/you/projects/web

On every restore, resurrect rebuilds the layout and then runs the post-restore hook. The hook starts a detached worker so the tmux server isn't blocked. For each pane that was running claude in the snapshot, the worker checks the pane exists and is sitting at a bare shell. It checks that the conversation file still exists under ~/.claude/projects/, then types claude --resume into that pane. It waits 7 seconds between panes.

The registry file is internal

`~/.claude/sessions/.json` isn't a documented Claude Code interface, so its format could change. The hooks are written to degrade safely: if a pane has no usable entry, it falls back to `claude --continue`, which resumes the most recent conversation in that folder. Both flags are documented in the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference).

What you need

Step 1: Install tpm

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Step 2: Add the config to ~/.tmux.conf

Paste this at the end of ~/.tmux.conf. The run line for tpm has to stay last.

# ---- tmux-resurrect + continuum + Claude Code resume ----
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Resurrect: restore editors + scrollback, re-run safe long-lived programs.
set -g @resurrect-strategy-vim 'session'
set -g @resurrect-strategy-nvim 'session'
set -g @resurrect-capture-pane-contents 'on'
# 'claude' is deliberately NOT listed: the post-restore hook relaunches it,
# staggered, resuming each pane's exact conversation.
set -g @resurrect-processes 'ssh vim nvim man less more tail top htop watch python python3 node'

# Hooks: map pane -> Claude session on every save; relaunch on every restore.
set -g @resurrect-hook-post-save-all '$HOME/.tmux/resurrect-hooks/save-claude-sessions.sh'
set -g @resurrect-hook-post-restore-all '$HOME/.tmux/resurrect-hooks/relaunch-claude.sh'

# Continuum: autosave every 15 min, auto-restore when the tmux server starts.
set -g @continuum-restore 'on'
set -g @continuum-save-interval '15'

# Init TPM (keep this line last)
run '~/.tmux/plugins/tpm/tpm'

Two details matter here:

Step 3: Add the fallback launcher

Save this as ~/.local/bin/claude-resume and make it executable. The restore hook uses it when a pane has no exact match in the map. It resumes the latest conversation for the pane's folder, or starts fresh if there isn't one.

#!/usr/bin/env bash
# claude-resume β€” start Claude Code, resuming the most recent conversation for
# the current directory if one exists, otherwise start a fresh session.
# Any extra arguments are passed straight through to `claude`.
#
# Used as the relaunch command by the tmux-resurrect post-restore hook so that
# restored panes come back to their previous conversation instead of blank.
set -u

# Claude stores per-directory conversations under ~/.claude/projects/<slug>,
# where <slug> is the absolute cwd with every non-alphanumeric char -> '-'.
slug=$(printf '%s' "$PWD" | sed 's/[^A-Za-z0-9]/-/g')
store="$HOME/.claude/projects/$slug"

if compgen -G "$store/*.jsonl" >/dev/null 2>&1; then
    # A prior conversation exists for this directory -> resume the latest one.
    exec claude --continue "$@"
else
    # Nothing to resume here -> start clean (avoids --continue's "no conversation" error).
    exec claude "$@"
fi

Step 4: Add the save hook

Save as ~/.tmux/resurrect-hooks/save-claude-sessions.sh:

#!/usr/bin/env bash
# tmux-resurrect post-save hook.
#
# For every live pane currently running `claude`, record an exact mapping of
#   <session>:<window>.<pane>  ->  <claude sessionId>  ->  <cwd>
# into a sidecar map, so the post-restore hook can relaunch each pane with
# `claude --resume <sessionId>` (per-pane fidelity, even for multiple panes
# sharing one directory).
#
# Mapping source: ~/.claude/sessions/<pid>.json, which Claude writes per running
# session as {"pid":...,"sessionId":...,"cwd":...}. We resolve each pane's live
# `claude` pid from its process subtree and look it up there.
set -u

MAP="${CLAUDE_SESSION_MAP:-$HOME/.local/share/tmux/resurrect/claude-sessions.map}"
SESS_DIR="${CLAUDE_SESSIONS_DIR:-$HOME/.claude/sessions}"
LOG="${CLAUDE_RESTORE_LOG:-$HOME/.local/share/tmux/resurrect/relaunch.log}"

log() { printf '%(%Y-%m-%dT%H:%M:%S)T [save] %s\n' -1 "$1" >> "$LOG" 2>/dev/null; }

# Find the first pid in a process subtree whose comm is exactly `claude`.
find_claude_pid() {
    local root="$1" depth="${2:-4}" p
    [ "$(ps -o comm= -p "$root" 2>/dev/null)" = "claude" ] && { printf '%s' "$root"; return 0; }
    [ "$depth" -le 0 ] && return 1
    for p in $(pgrep -P "$root" 2>/dev/null); do
        local found; found="$(find_claude_pid "$p" $((depth - 1)))" && { printf '%s' "$found"; return 0; }
    done
    return 1
}

tmp="$(mktemp "${MAP}.XXXXXX")" || exit 0
trap 'rm -f "$tmp"' EXIT

mapped=0; skipped=0
seen_sids=""
while IFS=' ' read -r pane_pid target cmd; do
    [ "$cmd" = "claude" ] || continue
    cpid="$(find_claude_pid "$pane_pid")" || { log "SKIP $target: no claude pid found under pane_pid=$pane_pid"; skipped=$((skipped+1)); continue; }
    reg="$SESS_DIR/${cpid}.json"
    [ -f "$reg" ] || { log "SKIP $target: no registry file $reg (claude_pid=$cpid)"; skipped=$((skipped+1)); continue; }
    # Pull sessionId + cwd without a JSON dep (fields are flat strings).
    sid="$(sed -n 's/.*"sessionId":"\([^"]*\)".*/\1/p' "$reg")"
    cwd="$(sed -n 's/.*"cwd":"\([^"]*\)".*/\1/p' "$reg")"
    [ -n "$sid" ] || { log "SKIP $target: empty sessionId in $reg"; skipped=$((skipped+1)); continue; }
    case " $seen_sids " in *" $sid "*) log "WARN $target: sessionId $sid already mapped to another pane -- concurrent resume of the same transcript";; esac
    seen_sids="$seen_sids $sid"
    printf '%s\t%s\t%s\n' "$target" "$sid" "$cwd" >> "$tmp"
    mapped=$((mapped+1))
done < <(tmux list-panes -a -F '#{pane_pid} #{session_name}:#{window_index}.#{pane_index} #{pane_current_command}' 2>/dev/null)

log "wrote $mapped mapping(s), $skipped claude pane(s) skipped"
mv -f "$tmp" "$MAP" 2>/dev/null && trap - EXIT
exit 0

Step 5: Add the restore hook

Save as ~/.tmux/resurrect-hooks/relaunch-claude.sh:

#!/usr/bin/env bash
# tmux-resurrect post-restore hook.
#
# After a restore (including continuum's automatic restore on tmux server start),
# relaunch Claude in panes that had it, resuming the EXACT prior conversation:
#   - If the sidecar map (written by save-claude-sessions.sh) has a sessionId for
#     this pane and that session file still exists -> `claude --resume <id>`.
#   - Otherwise fall back to `claude-resume` (most-recent convo for the cwd).
#
# Launches are STAGGERED (default 7s apart) and run detached, so a mass restore
# can't spawn every Claude session at once (OOM / rate-limit guard). Panes not
# sitting at a shell prompt are skipped, so nothing live is ever disturbed.
#
# Every decision (launch / skip-and-why) is appended to CLAUDE_RESTORE_LOG β€”
# the original version discarded all stderr, so a silent skip (a pane not yet
# settled, a stale/renumbered target) left no trail to diagnose after the fact.
set -u

SNAP="${CLAUDE_RESTORE_SNAP:-$HOME/.local/share/tmux/resurrect/last}"
MAP="${CLAUDE_SESSION_MAP:-$HOME/.local/share/tmux/resurrect/claude-sessions.map}"
PROJ="${CLAUDE_PROJECTS_DIR:-$HOME/.claude/projects}"
RESUME_CMD="${CLAUDE_RESUME_CMD:-claude-resume}"   # cwd-based fallback
CLAUDE_CMD="${CLAUDE_CMD:-claude}"                 # for --resume <id>
STAGGER="${CLAUDE_RESTORE_STAGGER:-7}"             # seconds between launches
SETTLE="${CLAUDE_RESTORE_SETTLE:-2}"              # let restored shells settle
LOCK="${CLAUDE_RESTORE_LOCK:-/tmp/.claude-restore-relaunch.lock}"
LOG="${CLAUDE_RESTORE_LOG:-$HOME/.local/share/tmux/resurrect/relaunch.log}"

log() { printf '%(%Y-%m-%dT%H:%M:%S)T [relaunch] %s\n' -1 "$1" >> "$LOG" 2>/dev/null; }

log "hook fired (snap=$SNAP map=$MAP)"

[ -e "$SNAP" ] || { log "abort: no snapshot symlink"; exit 0; }
snap="$(readlink -f "$SNAP" 2>/dev/null)"
[ -f "$snap" ] || { log "abort: snapshot target missing: $snap"; exit 0; }

# cwd -> Claude projects slug (every non-alphanumeric char -> '-').
slug_of() { printf '%s' "$1" | sed 's/[^A-Za-z0-9]/-/g'; }

# Detach the staggered worker so the tmux server is not blocked during restore.
(
  exec 9>"$LOCK"
  if ! flock -n 9; then
      log "abort: another relaunch pass already holds $LOCK"
      exit 0
  fi

  # Load sidecar map: target -> sessionId, target -> cwd.
  declare -A SID CWD
  if [ -f "$MAP" ]; then
      while IFS=$'\t' read -r t s c; do
          [ -n "$t" ] || continue
          SID["$t"]="$s"; CWD["$t"]="$c"
      done < "$MAP"
      log "loaded map: ${#SID[@]} entries"
  else
      log "no sidecar map at $MAP -- every pane falls back to $RESUME_CMD"
  fi

  sleep "$SETTLE"
  i=0
  # Snapshot pane line: pane <session> <window> <f4> <flags> <pane> <title> :<path> <active> <command> :<full>
  while IFS=$'\t' read -r tag session win f4 flags pane title path active cmd full; do
      [ "$tag" = "pane" ] || continue
      [ "$cmd" = "claude" ] || continue

      target="${session}:${win}.${pane}"

      # Pane must exist and currently be sitting at a shell prompt.
      if ! cur="$(tmux display-message -p -t "$target" '#{pane_current_command}' 2>&1)"; then
          log "SKIP $target: pane does not exist (display-message: $cur)"
          continue
      fi
      case "$cur" in
          bash|sh|zsh|fish) : ;;   # safe to relaunch into
          *) log "SKIP $target: pane_current_command=$cur (not a bare shell)"; continue ;;
      esac

      # Decide the launch command: exact resume if we have a valid sessionId.
      launch="$RESUME_CMD"
      sid="${SID[$target]:-}"
      if [ -n "$sid" ]; then
          cwd="${CWD[$target]:-${path#:}}"
          if [ -f "$PROJ/$(slug_of "$cwd")/$sid.jsonl" ]; then
              launch="$CLAUDE_CMD --resume $sid"
          else
              log "$target: map had sid=$sid but no transcript at $PROJ/$(slug_of "$cwd")/$sid.jsonl -- falling back to $RESUME_CMD"
          fi
      else
          log "$target: no sidecar map entry -- falling back to $RESUME_CMD"
      fi

      [ "$i" -gt 0 ] && sleep "$STAGGER"
      if tmux send-keys -t "$target" "$launch" Enter 2>>"$LOG"; then
          log "LAUNCH $target: $launch"
      else
          log "FAIL $target: send-keys failed for: $launch"
      fi
      i=$((i + 1))
  done < "$snap"

  log "done: $i pane(s) launched"
) </dev/null >/dev/null 2>&1 &

disown 2>/dev/null || true
exit 0

Then make everything executable, install the plugins and reload:

mkdir -p ~/.tmux/resurrect-hooks ~/.local/bin
chmod +x ~/.tmux/resurrect-hooks/*.sh ~/.local/bin/claude-resume
tmux source-file ~/.tmux.conf    # inside tmux; then press prefix + I to install the plugins

Step 6: Test it without risking your real sessions

Restoring into a live tmux server is disruptive, so test against a throwaway one first. tmux finds a running server by its socket, not by $HOME. A test that only changes $HOME will still talk to your real server. Use a private socket with -L:

# a separate tmux server, invisible to your normal one
tmux -L rstest new-session -d -s work
tmux -L rstest send-keys -t work 'claude' Enter
# ...wait until Claude is up, then save:
tmux -L rstest run-shell ~/.tmux/plugins/tmux-resurrect/scripts/save.sh
cat ~/.local/share/tmux/resurrect/claude-sessions.map
tail ~/.local/share/tmux/resurrect/relaunch.log

You should see one map line per Claude pane and a [save] wrote N mapping(s) line in the log. Then clean up straight away:

tmux -L rstest kill-server      # it loads your config, so left running its continuum would autosave over your real snapshot

Back in your real tmux, press prefix + Ctrl-s once. The test server shares your normal resurrect folder, so this puts your real layout and map back as the latest save.

That's the run you see in the video above. We built a sandbox $HOME with exactly this config, started four Claude panes, saved, killed the tmux server, restored, and watched each pane relaunch into its own session ID. The terminal footage uses a small stand-in for claude, so no real conversation or account data appears on screen.

Day-to-day use

ActionKeys / command
Save nowprefix + Ctrl-s
Restore the last saveprefix + Ctrl-r
AutosaveEvery 15 minutes, automatically
Auto-restoreWhen the tmux server starts (see the first gotcha below)
See what the hooks didtail -n 30 ~/.local/share/tmux/resurrect/relaunch.log

Every hook decision is logged with a reason: LAUNCH, SKIP … not a bare shell, falling back to claude-resume, and so on. When a pane doesn't come back the way you expected, the log tells you why.

Gotchas we hit (and the fixes)

Continuum won't auto-restore if another tmux server is running

On startup, continuum only auto-restores when it looks like the first tmux server on the machine. It counts tmux processes. If a second server is already up (another socket, a test server, a tool that runs its own tmux), auto-restore is skipped without any message. Press `prefix + Ctrl-r` to restore by hand.

Autosave stops if a theme overwrites status-right. Continuum triggers its timed saves through the status line, so the status line must be on. If a theme or plugin replaces status-right after continuum loads, autosave stops. The continuum README says to list it last among your plugins. Check with tmux show -gv status-right; it should contain continuum_save.sh.

Panes are login shells. tmux starts each pane as a login shell, which reads ~/.bash_profile, not ~/.bashrc. If your prompt or PATH looks wrong in restored panes, make sure ~/.bash_profile sources ~/.bashrc. If claude isn't on the PATH there, every relaunch fails.

"no registry file" in the log. Sometimes the save hook finds a claude process but no ~/.claude/sessions/.json for it. The hook skips that pane and logs it, and on restore the pane falls back to claude-resume. You get the latest conversation for that folder instead of the exact one.

"sessionId already mapped to another pane". Two panes are running the same conversation, for example after resuming it twice by hand. Both will resume it on restore. That works, but two live sessions writing to one conversation is rarely what you want, so the log warns you.

Don't add claude to @resurrect-processes. It's worth repeating: that path starts new conversations, all at once.

Keeping secrets out of it

FAQ

Does this work with multiple Claude Code sessions in the same folder?

Yes. That's the main reason for the save hook. It records the exact session ID per pane, so two panes in one project come back to their own conversations. The folder-based claude --continue is only the fallback.

Will a restore interrupt anything that's running?

No. The restore hook only types into a pane whose current command is a plain shell (bash, sh, zsh or fish). Anything else is skipped and logged. A lock file also stops two restore passes from overlapping.

Why wait 7 seconds between panes?

Starting a dozen Claude sessions at the same moment spikes memory and fires a burst of startup requests. Spacing them out keeps the machine responsive. Change it with the CLAUDE_RESTORE_STAGGER environment variable (in seconds), as long as it's set in the tmux server's environment.

Does it survive a full reboot?

Yes, as long as tmux starts after the reboot: continuum auto-restores when the server starts. To have tmux itself start at boot, see continuum's "automatic tmux start" option. If auto-restore doesn't fire, prefix + Ctrl-r always works.

Can I use zsh instead of bash?

Yes. The hooks run under bash, but the panes can use any shell. The restore check already accepts zsh and fish.

The short version

Install tpm, resurrect and continuum, then add two hooks: one maps panes to Claude session IDs on every save, the other relaunches each pane with claude --resume on restore, one at a time. Test on a private -L socket first, keep an eye on relaunch.log, and keep the resurrect folder private because it holds your scrollback.

We set up agent workflows like this for teams: reliable, logged, and without leaking secrets. See our AI automation services, see how we build agentic solutions, or get in touch for a free consultation.