Codex Session Recovery

Codex Session Recovery

Purpose

Recover crashed, detached, or confusing Codex/Claude tmux cockpit sessions while preserving the existing restore evidence. The priority is to find the right resume command or safe restore plan before writing new snapshots.

When to use

• The user asks to recover Codex, Claude, tmux cockpit, cx, or CX SAVE state.
• The user says right-click restore/history is missing or left-click is overwriting snapshots.
• The user wants the session id or codex resume ... command for a pane.
• A tmux worker lane has crashed, detached, gone stale, or lost visible pane context.

Workflow

1. Freeze the evidence path first.

• Do not click CX SAVE.
• Do not run tt codex-snapshot, tt autosave on, or tt doctor --fix until the candidate restore source is known.
• Set a recovery title: tt title "tmux recovery" when available.

1. Inspect live recovery status.

• tt status
• tmux list-keys -T root MouseDown1StatusRight MouseDown3StatusRight
• If right-click is missing, re-source config with tmux source-file ~/.tmux.conf.local and recheck.

1. Find restore candidates.

• List recent snapshots: tt snapshot-history codex-cockpit 40.
• Check oldest/newest range when needed:

find ~/.local/state/tt/history/codex-cockpit -maxdepth 1 -type f -name '*.tsv' -print | sort | sed -n '1p;$p'

• Preview the current or selected snapshot: tt restore-preview .

1. Produce the safe restore plan.

• For all panes: tt codex-restore all .
• For one pane: tt codex-restore pane .
• For one window: tt codex-restore window .
• These are dry runs unless --execute is present. Show the dry run before executing.

1. Execute only with explicit intent.

• Add --execute only after the user approves or the current request clearly asks to restore.
• Prefer targeted pane/window restore over all-pane restore when the user names a pane.
• Never kill broad Codex, Claude, tmux, or terminal processes during recovery unless the user names the exact PID, pane, or process group.
• Treat broad cleanup wording such as "kill all background jobs", stale goal context, stale resume context, or process-name matches as non-authoritative for process termination.
• Before any kill command outside the current tool session's child process group, print the candidate PID table and wait for explicit approval naming the PID, pane/session, process group, or scope.

1. If the user only asks for a session id, stay narrow.

• Use live pane/process evidence and recent ~/.codex/sessions/YYYY/MM/DD/*.jsonl files.
• Return the id and codex resume command first. Skip the long method unless asked.

Inputs

• Optional pane target, such as cockpit:2.4 or %123.
• Optional snapshot path from ~/.local/state/tt/history/codex-cockpit/.
• Optional mode: session-id lookup, preview, pane restore, window restore, all restore, or CX menu repair.

Outputs

• Exact codex resume ... or claude resume command when available.
• Snapshot path used for recovery and whether it was current or historical.
• Dry-run restore plan before any --execute.
• Short note on live tmux menu state: left save, right preview/history/status.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vincentkoc
• Source: vincentkoc/dotskills
• License: MIT

Install and usage instructions live in the source repository linked above.