BjornMelin/dev-skills / archive/skills/codex-session-cleanup
codex-session-cleanup
UnverifiedSafely scan, triage, quarantine, restore, and purge Codex session/history/state/memory artifacts for current repo, explicit roots, subrepos, Codex-home, or all sessions.
Codex Session Cleanup
Use this explicit-only skill for Codex artifact hygiene from any directory. Default to a read-only scan that produces a JSON manifest and Markdown report. Quarantine is reversible cleanup; purge is irreversible cleanup.
Safety Contract
- Never delete directly. Quarantine first, purge later.
- Never mutate during
scan. - Never clean all sessions unless the user explicitly asks for all sessions.
- Never move, ignore, rewrite, or delete active memory by default. Copy memory summaries and the memory registry into quarantine when cleanup runs.
- Never inspect or mutate
auth.json,internal_storage/**, or secret-like env files unless the user explicitly requests a separate security-reviewed workflow. - Stop on SQLite integrity failures, JSONL parse errors, checksum mismatch, ambiguous thread IDs, active/recent session risk, active jobs/goals, child spawn risk, stale manifests, or missing backups.
First-Pass Workflow
- Load only the references needed:
references/artifact-model.mdfor Codex file and DB layout.references/classifier-rules.mdfor confidence, scope, and memory triage.references/safety-restore.mdbeforeapply,restore, orpurge.references/report-template.mdwhen interpreting output.
- Run a scan first. From a repo, this scans the current Git root and audits linked memory without mutating anything:
python3 "$skill_dir/scripts/codex_session_cleanup.py" scan
- Review the report sections for scope roots, selected threads, medium candidates, protected exclusions, memory triage, artifact families, and automation eligibility.
- Use existing read-only subagents only when the report is ambiguous or broad:
repo_explorerfor scope sanity,false_positive_validatorfor candidate risk, andhistory_reviewerfor durable-memory review. - Apply only with the exact manifest id and
--execute; keep memory copy-first:
python3 "$skill_dir/scripts/codex_session_cleanup.py" apply \
--manifest /path/to/manifest.json \
--confirm <manifest-id> \
--memory-policy copy \
--execute
- Rerun
scanafter cleanup and report counts, quarantine path, DB integrity, checksum status, history/index rows removed, session files quarantined, memory files copied/moved, automation blockers, and remaining risk.
Scopes
- Current repo or directory:
scan - Explicit root:
scan --scope root --root /path/to/repo - Multiple roots:
scan --scope roots --root /repo/a --root /repo/b - Roots file:
scan --scope roots --roots-file /path/to/roots.txt - Repositories under cwd:
scan --scope cwd-subrepos --cwd /path/to/parent - Codex-home artifacts only:
scan --scope codex-home - All Codex sessions/artifacts:
scan --scope all
Nested repositories use longest-root-wins ownership unless
--include-parent-overlap is explicit.
Artifact Families
Default scan families are sessions plus memory. Add repeatable
--artifact-family values when needed:
sessions: session JSONL, history/index JSONL, state/log SQLite rows.memory:memories/MEMORY.mdand linked rollout summaries, copy-first.quarantine: old quarantine bundles, purge remains manual.logs: Codex logs and log directories, report-only by default.cache: cache and temp directories, manual candidate only.generated: generated images, manual candidate only.skills-agents-config: skills, agents, AGENTS/config files, report-only.
Autonomous Apply Policy
Autonomous apply is allowed only for reversible quarantine of high-confidence
current-repo disposable session artifacts when scan evidence and read-only
validator consensus agree false-positive risk is low. Autonomous apply must use
--memory-policy copy; active memory files must not be moved, deleted, or
rewritten.
Manual review is required for medium-confidence candidates, broad all-session sweeps, active/recent sessions, ambiguous IDs, parse or integrity issues, durable linked memory, destructive memory mutation, and purge.
Memory Policy
Treat stale, outdated, or conflicting memory as a live-verification queue, not as proof that the memory should be deleted. Preserve durable workflow knowledge and mark drift-prone details in the report. Current repo code/docs and live provider or GitHub state outrank historical memory when they conflict.
Destructive memory modes require an extra manifest-id confirmation:
python3 .../codex_session_cleanup.py apply ... \
--memory-policy move \
--confirm-memory-move <manifest-id> \
--execute
Implementation Notes
The script is the source of truth for deterministic scanning and mutation. Use the references for policy and interpretation, not for hand-written cleanup commands. Prefer adding classifier or artifact-family behavior to the script over ad hoc shell filters.
Validate after changes:
python3 -m py_compile "$skill_dir/scripts/codex_session_cleanup.py"
python3 -m unittest discover -s "$skill_dir/tests"
python3 "<skill-creator-dir>/scripts/quick_validate.py" "$skill_dir"
node "<skill-auditor-dir>/scripts/audit-skills-baseline.mjs" "<skills-root>" /tmp/codex-session-cleanup-skill-audit
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: 467k | 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: 319k | 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: 319k | 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: 319k | Updated | Claude CodeCodex | Verified | Install |