Codex Cleaner

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

1. Start with an audit unless the user already provided recent audit output.
2. Inspect storage by metadata only:

``bash python3 scripts/codex_cleaner.py audit ``

1. Explain the largest storage areas in plain language and separate report-only database files from cleanup candidates.
2. Propose the smallest useful cleanup command before running cleanup.
3. Run cleanup first as a dry run:

``bash python3 scripts/codex_cleaner.py clean --target sessions --older-than 60 ``

1. 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 for fixtures or non-default local testing. Use --top 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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: daniel-p-green
• Source: daniel-p-green/codex-cleaner
• License: MIT

Install and usage instructions live in the source repository linked above.