Codex cleaner

A Codex skill for auditing and safely cleaning local Codex storage

Install

npx -y skills add daniel-p-green/codex-cleaner

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.1 KB, as published. Nobody here has run it

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.