feat: restore claude/codex agent CLI sessions on restore

Add session restore strategies for the `claude` and `codex` agent CLIs:
on restore a bare launch is rewritten to resume the most recent
conversation for the pane (`claude --continue`, `codex resume --last`),
while an explicit `--resume`/`-r` (claude) or `resume`/`fork` (codex) is
preserved. Both are wired into the default process list and registered to
the `session` strategy, so it works with no configuration.

Adapted from upstream tmux-resurrect tmux-plugins#558 (framework-native strategy
mechanism, no hooks/python/sqlite, tested) over tmux-plugins#571 (heavy SessionStart
hook + python + manual settings.json) and tmux-plugins#572 (vibe-coded fuzzy SQLite
matching, no tests). Resume detection also recognizes claude's short
`-c`/`-r` with whole-token matching. Reviewed PRs tracked in
docs/upstream-pr-review.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: claude

CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-### Unreleased
+### v5.1.1, 2026-06-22
+
+- Restores AI agent CLI sessions. `claude` and `codex` panes now resume their
+  most recent conversation on restore (`claude --continue`, `codex resume
+  --last`) instead of launching empty; an explicit `--resume`/`-r` (claude) or
+  `resume`/`fork` (codex) you already typed is preserved. Both are in the default
+  process list, so it works with no configuration. See
+  [restoring AI agent CLI sessions](docs/restoring_agent_sessions.md). Adapted
+  from upstream tmux-resurrect [#558](https://github.com/tmux-plugins/tmux-resurrect/pull/558);
+  see [`docs/upstream-pr-review.md`](docs/upstream-pr-review.md) for the
+  comparison against [#571](https://github.com/tmux-plugins/tmux-resurrect/pull/571)
+  and [#572](https://github.com/tmux-plugins/tmux-resurrect/pull/572).
 
 - Saves whose content is byte-identical to a session's latest snapshot no longer
   write a duplicate file; the existing snapshot's mtime is refreshed instead so

README.md

@@ -69,6 +69,7 @@ This plugin goes to great lengths to save and restore all the details from your
 Optional:
 
 - [restoring vim and neovim sessions](docs/restoring_vim_and_neovim_sessions.md)
+- [restoring AI agent CLI sessions](docs/restoring_agent_sessions.md) (`claude`, `codex`)
 - [restoring a previously saved environment](docs/restoring_previously_saved_environment.md)
 
 Requirements / dependencies: `tmux 1.9` or higher, `bash`.
@@ -143,6 +144,8 @@ You should now be able to use the plugin.
 
 - [Restoring vim and neovim sessions](docs/restoring_vim_and_neovim_sessions.md)
   is nice if you're a vim/neovim user.
+- [Restoring AI agent CLI sessions](docs/restoring_agent_sessions.md) resumes the
+  most recent `claude` / `codex` conversation per pane, enabled by default.
 - [Restoring pane contents](docs/restoring_pane_contents.md) is enabled by
   default; this doc explains how to tune or disable it.
 

docs/restoring_agent_sessions.md

@@ -0,0 +1,55 @@
+# Restoring AI agent CLI sessions
+
+[Claude Code](https://docs.claude.com/en/docs/claude-code) (`claude`) and
+[Codex CLI](https://github.com/openai/codex) (`codex`) cannot be resumed by
+re-launching the bare process: each conversation lives behind a session id, and
+a fresh launch starts an empty one. `tmux-persist` restores them through its
+normal [restore strategy](restoring_programs.md) mechanism, so no hooks,
+sidecar files, or extra dependencies are involved.
+
+Both are restored **by default** — `claude` and `codex` are in the default
+process list and registered to the `session` strategy. There is nothing to
+configure.
+
+## How it works
+
+On restore, each tool's strategy rewrites the captured command into the CLI's
+own "resume the most recent conversation here" form:
+
+| Saved command | Restored command |
+|---|---|
+| `claude` | `claude --continue` |
+| `claude --model opus` | `claude --model opus --continue` |
+| `claude --continue` / `claude -c` | unchanged |
+| `claude --resume <id>` / `claude -r <id>` | unchanged |
+| `codex` | `codex resume --last` |
+| `codex fix the bug` | `codex resume --last` |
+| `codex resume <id>` / `codex fork <id>` | unchanged |
+
+`claude --continue` and `codex resume --last` ask each CLI to reopen the most
+recent conversation for the pane's working directory. An explicit
+`--resume`/`-r` (claude) or `resume`/`fork` subcommand (codex) the user already
+typed is always left untouched, so a deliberately pinned session wins.
+
+## Disabling
+
+To stop restoring one of them, override the process list without it:
+
+    set -g @persist-processes 'claude'   # restore claude only, not codex
+
+Or point its strategy elsewhere / clear it:
+
+    set -g @persist-strategy-codex ''
+
+## Limitation: multiple panes, same directory
+
+"Most recent conversation here" is keyed by working directory. If several panes
+ran the same agent in the *same* directory, they all resume to the single
+newest conversation; the others are not individually re-targeted. Pinning a
+pane with an explicit `claude --resume <id>` / `codex resume <id>` before saving
+avoids the collapse, because the explicit command is preserved verbatim.
+
+Per-pane session capture would need each CLI to expose its running session id
+externally (so save time could record it). Until then `--continue` /
+`resume --last` is the dependency-free behavior that is correct for the common
+one-agent-per-directory case.

docs/upstream-pr-review.md

@@ -0,0 +1,33 @@
+# Upstream PR Review (tmux-resurrect → tmux-persist)
+
+Tracks which open [tmux-resurrect](https://github.com/tmux-plugins/tmux-resurrect)
+pull requests have been evaluated against this fork, the verdict, and what (if
+anything) the fork adopted. Companion to [`upstream-triage.md`](upstream-triage.md),
+which covers upstream *issues*.
+
+| PR | Title | Reviewed | Verdict | Outcome in fork |
+|---|---|---|---|---|
+| [#558](https://github.com/tmux-plugins/tmux-resurrect/pull/558) | Add Claude Code and Codex CLI session restore | 2026-06-22 | **Adopted (base)** | Ported `claude`/`codex` `session` strategies + default-list wiring + tests. See [`restoring_agent_sessions.md`](restoring_agent_sessions.md). |
+| [#571](https://github.com/tmux-plugins/tmux-resurrect/pull/571) | Restore claude sessions via `--resume <id>` | 2026-06-22 | Rejected | Heavy: needs a `SessionStart` hook, `python3`, and manual `settings.json` edits for per-pane mapping; its basic mode hand-reads `~/.claude/projects/*.jsonl` instead of using `claude --continue`. Per-pane correctness noted as a [known limitation](restoring_agent_sessions.md#limitation-multiple-panes-same-directory). |
+| [#572](https://github.com/tmux-plugins/tmux-resurrect/pull/572) | Resurrect `copilot`, `agy`, `codex` CLIs | 2026-06-22 | Rejected | One large pre-save hook that fuzzy-matches pane text against app SQLite DBs (`session-store.db`, `state_5.sqlite`) and process logs; author-flagged "vibe-coded", no tests, fragile across CLI/DB-schema changes. Codex coverage met by #558 instead. |
+
+## Why #558 over #571 / #572
+
+- **Framework-native.** #558 uses the existing per-process restore-strategy
+  mechanism (`strategies/<cmd>_session.sh` + `@persist-strategy-<cmd>`), the same
+  path `vim`/`nvim` use. #571 and #572 bolt on out-of-band machinery (settings
+  hooks, sqlite reads, pane-text scraping).
+- **No external dependencies.** No `python3`, no `sqlite3`, no per-session
+  sidecar files, no edits to the agents' own config.
+- **Tested + deterministic.** Pure command rewrite, covered by
+  [`tests/test_agent_strategies.sh`](../tests/test_agent_strategies.sh).
+- **Resilient.** Defers to each CLI's own resume (`claude --continue`,
+  `codex resume --last`) rather than depending on an on-disk layout or DB schema
+  that can change without notice.
+
+### Improvements over #558 as merged
+
+- Resume detection also recognizes claude's short flags `-c` / `-r`, with
+  whole-token matching so a `--continue` inside a prompt argument can't trip it.
+- Wired as fork defaults via `persist.tmux` `set_default_strategies` and the
+  `@persist-` option namespace (not the upstream `@resurrect-` names).

persist.tmux

@@ -24,6 +24,8 @@ set_restore_bindings() {
 set_default_strategies() {
 	tmux set-option -gq "${restore_process_strategy_option}irb" "default_strategy"
 	tmux set-option -gq "${restore_process_strategy_option}mosh-client" "default_strategy"
+	tmux set-option -gq "${restore_process_strategy_option}claude" "session"
+	tmux set-option -gq "${restore_process_strategy_option}codex" "session"
 }
 
 set_script_path_options() {

scripts/variables.sh

@@ -9,7 +9,7 @@ restore_path_option="@persist-restore-script-path"
 
 # default processes that are restored
 default_proc_list_option="@persist-default-processes"
-default_proc_list='vi vim view nvim emacs man less more tail top htop irssi weechat mutt'
+default_proc_list='vi vim view nvim emacs man less more tail top htop irssi weechat mutt claude codex'
 
 # User defined processes that are restored
 #  'false' - nothing is restored

strategies/claude_session.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+# "claude session strategy"
+#
+# Claude Code's `claude` CLI cannot be resumed by re-launching the bare process:
+# every conversation lives behind a session UUID. The CLI's own
+# `claude --continue` reopens the most recent conversation for the pane's
+# working directory, which is exactly what restore wants and needs no sidecar
+# files, hooks, or knowledge of Claude's on-disk layout.
+#
+# Behavior:
+#   - If the saved command already resumes/continues (long or short flag),
+#     pass it through unchanged so the explicit choice wins.
+#   - Otherwise append `--continue`, preserving any other captured flags.
+
+ORIGINAL_COMMAND="$1"
+DIRECTORY="$2"
+
+original_command_already_resumes() {
+	# Whole-token match so a `--continue` inside a prompt arg never trips it and
+	# `-c` / `-r` short forms (claude's continue/resume) are caught too.
+	[[ "$ORIGINAL_COMMAND" =~ (^|[[:space:]])(--continue|--resume|-c|-r)([[:space:]=]|$) ]]
+}
+
+main() {
+	if original_command_already_resumes; then
+		echo "$ORIGINAL_COMMAND"
+	else
+		echo "$ORIGINAL_COMMAND --continue"
+	fi
+}
+main

strategies/codex_session.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# "codex session strategy"
+#
+# OpenAI's `codex` CLI resumes a prior conversation with the `resume`
+# subcommand; `codex resume --last` reopens the most recent one. As with
+# Claude Code, re-launching the bare process starts a brand new conversation,
+# so restore rewrites the captured command to resume the last session.
+#
+# Behavior:
+#   - If the saved command is already a `resume`/`fork` invocation, pass it
+#     through unchanged (it targets a specific session the user picked).
+#   - Otherwise restore the most recent session with `codex resume --last`.
+
+ORIGINAL_COMMAND="$1"
+DIRECTORY="$2"
+
+original_command_already_resumes() {
+	[[ "$ORIGINAL_COMMAND" =~ (^|[[:space:]])(resume|fork)([[:space:]]|$) ]]
+}
+
+main() {
+	if original_command_already_resumes; then
+		echo "$ORIGINAL_COMMAND"
+	else
+		echo "codex resume --last"
+	fi
+}
+main

tests/test_agent_strategies.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Agent CLI session restore: the claude/codex restore strategies rewrite a bare
+# launch into a resume, preserve an explicit resume, and are wired as defaults.
+
+source "$(dirname "$0")/helpers/test_helpers.sh"
+
+CLAUDE="$PLUGIN_DIR/strategies/claude_session.sh"
+CODEX="$PLUGIN_DIR/strategies/codex_session.sh"
+
+assert_strategy() { # script desc input expected
+	assert_eq "$("$1" "$3" "/some/dir")" "$4" "$2"
+}
+
+# --- claude_session.sh ---
+assert_strategy "$CLAUDE" "bare claude gets --continue" \
+	"claude" "claude --continue"
+assert_strategy "$CLAUDE" "claude flags preserved, --continue appended" \
+	"claude --model opus" "claude --model opus --continue"
+assert_strategy "$CLAUDE" "claude --continue not duplicated" \
+	"claude --continue" "claude --continue"
+assert_strategy "$CLAUDE" "claude --resume <id> preserved" \
+	"claude --resume abc123" "claude --resume abc123"
+assert_strategy "$CLAUDE" "claude short -c preserved" \
+	"claude -c" "claude -c"
+assert_strategy "$CLAUDE" "claude short -r <id> preserved" \
+	"claude -r abc123" "claude -r abc123"
+
+# --- codex_session.sh ---
+assert_strategy "$CODEX" "bare codex resumes last" \
+	"codex" "codex resume --last"
+assert_strategy "$CODEX" "codex with prompt resumes last" \
+	"codex fix the bug" "codex resume --last"
+assert_strategy "$CODEX" "codex --model flag still resumes last" \
+	"codex --model gpt-5" "codex resume --last"
+assert_strategy "$CODEX" "codex resume returned as-is" \
+	"codex resume" "codex resume"
+assert_strategy "$CODEX" "codex resume --last returned as-is" \
+	"codex resume --last" "codex resume --last"
+assert_strategy "$CODEX" "codex resume <id> preserved" \
+	"codex resume abc123" "codex resume abc123"
+assert_strategy "$CODEX" "codex fork <id> preserved" \
+	"codex fork abc123" "codex fork abc123"
+
+# --- wiring (default proc list + default strategy registration) ---
+source "$PLUGIN_DIR/scripts/variables.sh"
+assert_contains "$default_proc_list" "claude" "claude in default_proc_list"
+assert_contains "$default_proc_list" "codex"  "codex in default_proc_list"
+
+setup
+load_plugin
+strategies="$(tmuxp show-options -g 2>/dev/null)"
+teardown
+assert_contains "$strategies" "${restore_process_strategy_option}claude session" \
+	"claude registered as 'session' strategy"
+assert_contains "$strategies" "${restore_process_strategy_option}codex session" \
+	"codex registered as 'session' strategy"
+
+# --- strategy files are executable ---
+[ -x "$CLAUDE" ] && _ok "claude_session.sh executable" || _ko "claude_session.sh executable"
+[ -x "$CODEX" ]  && _ok "codex_session.sh executable"  || _ko "codex_session.sh executable"
+
+finish