Codex Upkeep

Preserve the useful part of old Codex sessions before reclaiming their disk space.

Codex Upkeep is a local-first Agent Skill and Python toolkit for auditing Codex Desktop/CLI storage, turning a calendar month of session rollouts into a compact recall archive, proving the archive against the original bytes, and previewing recoverable pruning behind explicit safety gates.

It does not send transcripts to an API. Runtime scripts use only the Python standard library.

Why

Heavy Codex use can accumulate gigabytes of JSONL rollouts, especially when agent teams create many worker sessions. Deleting them blindly saves space but destroys useful project continuity. Archiving everything byte-for-byte preserves privacy and history but barely reduces storage.

Codex Upkeep keeps the middle layer:

Audit → Recall → Verify → Preview → Explicit prune → Verify again

The recall archive contains project and daily Markdown, a structured JSONL catalog, and a SHA-256 deletion manifest. Pruning remains a separate decision.

Install the skill

npx skills add seunghyukchoe/codex-upkeep@codex-upkeep -g -y

Then ask Codex:

Use $codex-upkeep to audit my local Codex storage and build a verified recall archive before pruning anything.

Manual installation:

git clone https://github.com/seunghyukchoe/codex-upkeep.git
mkdir -p ~/.agents/skills/codex-upkeep
cp -R codex-upkeep/skills/codex-upkeep/. ~/.agents/skills/codex-upkeep/

Quick start

Resolve the installed skill directory and run its scripts with Python 3.10 or newer.

1. Read-only audit

python3 skills/codex-upkeep/scripts/audit_codex_storage.py --month 2026-07 --json

Normal audit output omits titles, prompt bodies, raw thread IDs, and process paths.

2. Build a private recall archive

The output must be outside CODEX_HOME and must not already contain files.

python3 skills/codex-upkeep/scripts/build_recall_archive.py \
  --month 2026-07 \
  --output ~/Documents/Codex-Recall/2026-07

Review and optionally curate MASTER_RECALL.md. The catalog and deletion manifest remain machine-owned integrity files.

3. Verify every original

python3 skills/codex-upkeep/scripts/verify_recall_archive.py \
  ~/Documents/Codex-Recall/2026-07 \
  --phase pre-prune

Verification checks cohort IDs, catalog/manifest digests, every originally present rollout's size and SHA-256, current-thread exclusion, and pinned-thread exclusion. A prune may be proposed only when both verified and prune_eligible are true.

4. Preview recoverable pruning

Official Codex deletion remains the first choice for normal individual tasks. For reviewed batch cleanup, legacy state, or residue verification, install the optional backend:

npm install -g codex-sessions-manager
python3 skills/codex-upkeep/scripts/prune_verified_sessions.py \
  ~/Documents/Codex-Recall/2026-07

Preview mode is read-only. It uses exact frozen IDs and relationship-aware plans.

5. Apply only after explicit approval

Prefer closing Codex before a large batch mutation. Copy the exact hash from verification.json:

python3 skills/codex-upkeep/scripts/prune_verified_sessions.py \
  ~/Documents/Codex-Recall/2026-07 \
  --apply --trash --yes \
  --confirm-verification <exact-verification-hash>

Only recoverable backend trash is supported. Codex Upkeep does not purge backend trash or empty macOS/Windows/Linux Trash.

What the archive keeps

• primary requests and completed-turn outcomes;
• daily and project retrieval views;
• worker/automation/internal classification;
• parent and agent metadata when available;
• relevant local paths and tool counts;
• original rollout existence, bytes, and SHA-256;
• missing/invalid/oversized-line diagnostics;
• a fixed thread-ID cohort for later verification.

It is recall-level evidence, not a verbatim replacement for every transcript event.

Proven workload

The initial real-world run processed a private month with 1,173 SQLite threads and 1,134 existing rollouts totaling 11,000,190,084 bytes. The final local recall archive was 14,897,013 bytes, a 99.86457% reduction, while preserving request flow for all 198 primary tasks and completed-turn outcomes for 184. All 1,134 existing rollouts passed byte-length and SHA-256 verification before deletion.

These figures are one workload, not a universal compression guarantee. See docs/benchmark.md.

Safety model

• read-only first run;
• no transcript upload;
• archive outside the deletion scope;
• exact manifest IDs, never age-only authorization;
• current and pinned thread blockers;
• fail-closed schema and digest checks;
• live revalidation immediately before mutation;
• recoverable backend trash only;
• separate approval for any later irreversible Trash purge;
• memories, attachments, generated media, automations, skills, plugins, and unrelated logs excluded by default.

Read docs/safety-model.md before using prune mode.

Documentation

• Architecture
• Safety model
• Archive benchmark
• Skill instructions
• Security policy
• Contributing

Compatibility

• Python 3.10+
• macOS and Linux are covered by CI with synthetic Codex homes.
• Windows path extraction is supported, but end-to-end Windows state testing is planned.
• Codex SQLite layouts are discovered from config.toml sqlite_home, CODEX_SQLITE_HOME, then CODEX_HOME.
• Unknown or incompatible state fails closed.

Development

python3 -m unittest discover -s tests -v
python3 -m compileall -q skills tests
ruff check .
ruff format --check .

Tests create temporary synthetic Codex homes and never access real user history.

License

MIT