LLMSkillHub
mirroredCopied from vincentkoc/dotskills under MIT. vincentkoc has not claimed this page, and is not affiliated with LLM SkillHub.

vincentkoc / codex-session-recovery

Recover Codex or Claude sessions from tmux panes, saved cockpit snapshots, session history, and recent agent logs without overwriting useful restore evidence. Use when a pane crashes, detaches, loses visible context, needs a resume command, or requires a safe targeted restore plan.

0
SKILL.md
3.2 KB

Codex Session Recovery

Purpose

Recover crashed, detached, or confusing agent sessions while preserving the best restore source.

When to use

  • Recover a Codex, Claude, or tmux cockpit session.
  • Find an exact codex resume <id> command.
  • Preview or restore saved pane/window/session state.
  • Repair missing snapshot history or tmux menu bindings.

Workflow

  1. Preserve evidence before writing state.

    • Do not create a new snapshot until the restore candidate is known.
    • Do not run repair commands that overwrite history.
    • Set a recovery pane title when possible.

  2. Inspect live tmux state.

    • tmux display-message -p '#S:#I.#P #{pane_current_command} #{pane_current_path}'
    • tmux list-panes -a -F '#S:#I.#P #{pane_pid} #{pane_current_command} #{pane_current_path}'
    • Inspect relevant key bindings before re-sourcing tmux configuration.

  3. Inspect available recovery sources.

    • Prefer the operator's snapshot/history helper when installed.
    • Inspect recent ~/.codex/sessions/YYYY/MM/DD/*.jsonl metadata for session IDs and working directories.
    • Cross-check pane PIDs, cwd, and recent logs before selecting a session.

  4. Produce a dry-run plan first.

    • Prefer one-pane or one-window restore over whole-session restore.
    • Show the snapshot or session ID, target pane, and exact command.

  5. Execute only with clear intent.

    • Require explicit intent before restore commands that mutate tmux state.
    • Never kill broad Codex, Claude, tmux, or terminal processes from name matches alone.
    • Restrict cleanup to the exact pane, PID, process group, or current-task resource.

  6. Stay narrow for session-ID requests.

    • Return the concrete ID and codex resume <id> first.
    • Add the broader recovery method only when requested.

Inputs

  • Optional tmux pane or window target.
  • Optional saved snapshot path.
  • Optional mode: session-ID lookup, preview, targeted restore, or menu repair.
  • Optional local snapshot helper such as tt.

Outputs

  • Exact resume command when available.
  • Selected restore source and target.
  • Dry-run restore plan before execution.
  • Concise blocker when evidence is insufficient.

Flow

stateDiagram-v2
    [*] --> PreserveRestoreEvidence
    PreserveRestoreEvidence --> MatchSourceAndTarget
    MatchSourceAndTarget --> ReportUnknown: identity or source ambiguous
    MatchSourceAndTarget --> ReturnResumeID: session-ID lookup
    MatchSourceAndTarget --> ShowExactPlan: preview or recovery
    ShowExactPlan --> ReportPlan: preview only or mutation not authorized
    ShowExactPlan --> TargetedRecovery: exact mutation authorized
    TargetedRecovery --> VerifyTarget
    VerifyTarget --> ReportResult
    ReportUnknown --> [*]
    ReturnResumeID --> [*]
    ReportPlan --> [*]
    ReportResult --> [*]