# Codex Context Repair

> Diagnose and repair local Codex conversations that cannot compact, are stuck after a context-full turn, show unfinished compact/task events, or need a manual recovery checkpoint. Use when the user says a Codex thread/context is full, compaction failed, a conversation cannot continue after compressing, a thread is stuck, or they want automatic repair of Codex session JSONL/state files.

- Skill: `zzc-cc/codex-context-repair` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zzc-cc/codex-context-repair`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zzc-cc/codex-context-repair/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ZZC-cc (https://skillmd.com/u/zzc-cc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zzc-cc/codex-context-repair

---


# Codex Context Repair

## Safety Rules

- Treat Codex local state as user data. Never delete or truncate session history.
- Always run diagnosis first unless the user explicitly asked for repair.
- Before repair, back up the target rollout JSONL to `C:\Users\Administrator\.codex\migration_backups`.
- Prefer repairing one explicit thread id. If several threads match a title/path, show candidates and ask the user to choose.
- Do not paste large JSONL/session contents into chat. Report ids, paths, counts, and concise findings.

## Workflow

1. Identify the affected thread:
   - Use a user-provided thread id when available.
   - Otherwise list likely threads by title, cwd, updated time, token count, and rollout path.
2. Diagnose:
   - Check `state_5.sqlite` for `threads`, `jobs`, and `stage1_outputs`.
   - Inspect the target `sessions/**/*.jsonl` tail for `task_started`, `task_complete`, `turn_aborted`, `compacted`, and `context_compacted`.
   - Measure large JSONL lines and recent `token_count` events.
3. Decide whether repair is appropriate:
   - Good candidate: a compact/task turn started but no completion event follows, or token count is near the model context window and no recent `context_compacted` was written.
   - Bad candidate: active current thread still running, missing rollout file, or multiple ambiguous matches.
4. Repair only with explicit intent:
   - Run `scripts/repair_codex_context.py --thread-id <id> --repair`.
   - The script appends a manual `turn_aborted` for an unfinished last task when needed.
   - The script appends a small `compacted` checkpoint containing a recovery summary and next-step prompt.
   - The script appends `context_compacted` after the checkpoint and refreshes `threads.updated_at`.
5. Verify:
   - Re-read the JSONL tail and confirm the final events are the manual compact checkpoint and `context_compacted`.
   - Tell the user to restart Codex if the UI still shows cached old state.

## Script

Use:

```powershell
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --thread-id <thread-id> --diagnose
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --thread-id <thread-id> --repair
```

Useful filters:

```powershell
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list --cwd-like "D:\Desktop"
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list --title-like "重构"
```

On Windows PowerShell, if Chinese filter text gets mangled, use thread id, cwd fragments without Chinese, or Unicode escapes through Python.