| name | codex-cleaner |
| description | This skill should be used when the user asks to clean up Codex logs, audit Codex storage, find large Codex sessions, reduce ~/.codex disk usage, archive old Codex chats, or mentions runaway Codex chat logs/storage. |
Codex Cleaner
Audit and clean local Codex storage safely. Focus on ~/.codex session files, logs, caches, generated artifacts, and temporary files without reading chat contents during audit.
Workflow
- Start with an audit unless the user already provided recent audit output.
- Inspect storage by metadata only:
python3 scripts/codex_cleaner.py audit
- Explain the largest storage areas in plain language and separate report-only database files from cleanup candidates.
- Propose the smallest useful cleanup command before running cleanup.
- Run cleanup first as a dry run:
python3 scripts/codex_cleaner.py clean --target sessions --older-than 60
- Require explicit user approval before adding
--execute.
Safety Rules
- Treat
~/.codex as the only v1 storage root unless the user passes a different root for testing.
- Use audit output to identify likely wins; do not inspect, summarize, or quote chat/log contents.
- Keep sqlite, WAL, and SHM files report-only. Do not delete, vacuum, checkpoint, or mutate live databases.
- Keep cleanup dry-run by default. Add
--execute only after the user confirms the exact command.
- Prefer archiving old sessions over deleting them directly.
- Skip symlinks and surface permission errors as warnings instead of forcing access.
Script Commands
Audit
Run:
python3 scripts/codex_cleaner.py audit
Use --root <path> for fixtures or non-default local testing. Use --top <count> to change how many large files and top-level entries are shown.
Audit reports:
- Total storage under the root.
- Top-level file and directory sizes.
- Session usage grouped by
YYYY-MM.
- Largest session
.jsonl files.
- Log, sqlite, WAL, and SHM files as report-only items.
- Special storage areas such as sessions, generated images, cache, tmp,
.tmp, and archived sessions.
Clean
Run dry-run cleanup:
python3 scripts/codex_cleaner.py clean --target sessions --older-than 60
Run confirmed cleanup:
python3 scripts/codex_cleaner.py clean --target sessions --older-than 60 --execute
Supported targets:
sessions: archive old session files to ~/.codex-cleaner/archives/ before deleting originals.generated-images: delete old top-level generated image entries.tmp: delete old top-level entries under tmp and .tmp.
Use --archive-root <path> only for fixture tests or when the user explicitly wants archives somewhere else.
Response Pattern
When reporting results, include:
- The root audited or cleaned.
- Total size and the top few storage areas.
- Cleanup candidates and estimated recoverable size.
- Whether the run was dry-run or executed.
- Any warnings or skipped paths.
Keep recommendations conservative. If the largest files are live databases or recent sessions, say they are report-only or should be kept unless the user has a specific retention policy.
