Agent-Skills.md

Agent Skills: Codex Session Cleanup

Safely scan, triage, quarantine, restore, and purge Codex session/history/state/memory artifacts for current repo, explicit roots, subrepos, Codex-home, or all sessions.

UncategorizedID: bjornmelin/dev-skills/codex-session-cleanup

Repository

bjornmelin/dev-skills
BjornMelin
8

Install this agent skill to your local

pnpm dlx add-skill https://github.com/BjornMelin/dev-skills/tree/HEAD/archive/skills/codex-session-cleanup

Skill Files

Browse the full folder contents for codex-session-cleanup.

Download Skill

Loading file tree…

archive/skills/codex-session-cleanup/SKILL.md

Skill Metadata

Name
codex-session-cleanup
Description
"Safely 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

  1. Load only the references needed:
    • references/artifact-model.md for Codex file and DB layout.
    • references/classifier-rules.md for confidence, scope, and memory triage.
    • references/safety-restore.md before apply, restore, or purge.
    • references/report-template.md when interpreting output.
  2. 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
  1. Review the report sections for scope roots, selected threads, medium candidates, protected exclusions, memory triage, artifact families, and automation eligibility.
  2. Use existing read-only subagents only when the report is ambiguous or broad: repo_explorer for scope sanity, false_positive_validator for candidate risk, and history_reviewer for durable-memory review.
  3. 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
  1. Rerun scan after 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.md and 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