sidiangongyuan/codex-skills-library / skills/codex-session-restore
codex-session-restore
VerifiedUse when Codex Desktop sidebar sessions disappear, fail with systemError, or cannot continue after a model_provider switch. Diagnoses and repairs active, non-archived sessions without changing authentication or provider configuration.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 6.3 KB |
| agents/openai.yaml | config | 291 B |
| references/recovery-checklist.md | markdown | 2.4 KB |
| scripts/restore_codex_sessions.py | script | 31.2 KB |
references/recovery-checklist.md
View on GitHub# Recovery Checklist
Use this checklist after `scan` or `scan-thread`.
## Provider Drift
- First determine the target provider from the user's current login/config goal.
`--provider` means "the provider Codex Desktop should recognize now," not
necessarily the provider that originally created the session.
- If the user is currently using official OAuth and wants old krill/custom
sessions visible again, repair active sessions with `--provider openai`.
- If the user explicitly wants to switch back to krill, then repair with
`--provider krill`.
- Do not edit `config.toml`, `auth.json`, cc-switch current-provider settings,
or third-party auth tokens unless the user explicitly asks to change
providers.
- If `threads.model_provider` differs from the target provider and rollout
`session_meta` has the old provider, repair both together.
- Prefer the provider in `${CODEX_HOME:-$HOME/.codex}/config.toml` when the user
does not specify one.
## Rollout Structure
- Parse errors or missing rollout files are blockers for bulk repair.
- Modern open turns have `turn_context.payload.turn_id`.
- Duplicate `turn_context` records for the same `turn_id` must be coalesced.
- Legacy `turn_context` records without `turn_id` are not safe mutation targets.
- Close stale modern turns with `turn_aborted`, not `task_complete`.
- Do not close open turns newer than 30 minutes unless the user confirms the
continuation is stale.
## Spawn Edges
- Close stale `thread_spawn_edges` only after the child rollout has no stale
modern open turns.
- Use the locally observed closed value: `closed`.
## Goals
- Report `active`, `blocked`, `usage_limited`, and `budget_limited` goals by
default.
- Complete a stale goal only when it is confirmed to block restore and the
repair command uses the explicit goal-completion flag.
## Archived Sessions
- Leave `${CODEX_HOME:-$HOME/.codex}/archived_sessions` and archived SQLite rows
untouched unless the user explicitly asks for archived repair and the command
includes `--include-archived`.
## Desktop Restart
- If verification is clean but Codex Desktop still shows missing threads or
`systemError`, restart Codex Desktop so the app server reloads session state
from disk.
- If an app thread-list tool is available, search for a known old title or id
before restart. Seeing old local sessions in the live list confirms the repair
is loaded even if the visible sidebar needs a refresh.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |