# Codex Session Recovery

> Recover Codex and Claude sessions from tmux cockpit panes, CX SAVE snapshots, codex-cockpit history, and recent Codex logs without overwriting the useful restore source first.

- **Type:** Skill
- **Install:** `agentstack add skill-vincentkoc-dotskills-codex-session-recovery`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vincentkoc](https://agentstack.voostack.com/s/vincentkoc)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vincentkoc](https://github.com/vincentkoc)
- **Source:** https://github.com/vincentkoc/dotskills/tree/main/private-skills/codex-session-recovery

## Install

```sh
agentstack add skill-vincentkoc-dotskills-codex-session-recovery
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. 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.
3. 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 `.
4. 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.
5. 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.
6. 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](https://github.com/vincentkoc)
- **Source:** [vincentkoc/dotskills](https://github.com/vincentkoc/dotskills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vincentkoc-dotskills-codex-session-recovery
- Seller: https://agentstack.voostack.com/s/vincentkoc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.