Task Cleaner removes tracked temporary files after Codex completes a task. It runs locally on macOS, with no Python packages or API keys required.
Codex puts disposable files in a task directory and marks it ready after the work is complete. Task Cleaner then removes those files. Save final outputs outside the task directory. Files from unfinished tasks stay available.
Run these commands from any directory. Codex downloads the released plugin for you.
codex plugin marketplace add senorMk/codex-task-cleaner --ref v0.1.2
codex plugin add task-cleaner@task-cleaner-localRequires macOS, Python 3.9 or later, lsof, and a Codex CLI version that supports codex plugin. No network service or scheduled job is needed for cleanup.
To update an existing installation, first run codex plugin marketplace remove task-cleaner-local, then run the install commands above.
Start a new Codex chat. Open /hooks and review and trust the two Task Cleaner hooks. Codex requires this trust step before local plugin hooks can run. Do not bypass hook trust. Installation alone does not activate the hooks.
For a first check, ask Codex to create a disposable file in the supplied task directory, complete the work, and mark the directory ready. After the turn, use the helper's list command to confirm a removed record.
UserPromptSubmitcreates a private directory for the session and turn.- The hook tells Codex where to put disposable files and how to set
TMPDIR,TMP, andTEMPfor shell commands. - After the work is complete, Codex saves deliverables outside the temporary directory, waits for processes, and marks the directory
ready. Stopchecks ready directories from that session and removes their contents.
Each directory is under /private/tmp/codex-task-cleaner-UID/ on macOS. On macOS, /tmp points to /private/tmp. Directory names are hashes of the session and turn identifiers. Records contain no prompts or file contents. Small records remain after cleanup for inspection. There is no automatic record expiry in this version.
The hook shows a short summary after cleanup:
Task Cleaner: Removed 3 task directories and 2 files (2.1 KiB).
For an empty task directory, the message shows zero files and zero bytes:
Task Cleaner: Removed 1 task directory and 0 files (0 B).
If cleanup cannot finish, the message gives the reason. Repeated reasons appear once. Command-line output stays in JSON format.
If a task record is missing or invalid, Task Cleaner keeps that task's files and continues to clean other ready tasks. It reports a new or changed record problem once. Run list to see each damaged record and its task directory. The list includes damaged records from all sessions. Inspect the directory before you remove any files.
Use the installed helper path supplied by the hook. In a source checkout:
python3 plugins/task-cleaner/scripts/cleaner.py list
python3 plugins/task-cleaner/scripts/cleaner.py ready TASK_ID
python3 plugins/task-cleaner/scripts/cleaner.py hold TASK_ID
python3 plugins/task-cleaner/scripts/cleaner.py clean TASK_ID
python3 plugins/task-cleaner/scripts/cleaner.py clean TASK_ID --applyclean without --apply is a preview. Removal requires a ready record. hold cancels readiness. Files needed by the user must be moved to a permanent location before readiness. Automatic removal is permanent; this plugin does not archive disposable files.
- Codex must use the supplied directory and mark it ready. Hooks cannot change the parent process environment or redirect arbitrary file writes. Existing files elsewhere in
/tmpand Codex's own internal temporary files are outside this plugin's scope. - A turn can end with a question. Unfinished work stays active until Codex marks it ready. An interruption or crash also leaves files for later inspection.
lsofmust complete without warnings. Open files, replaced directories, hard links, mounted filesystems, and special files prevent removal.- Internal symbolic links are removed without following their targets.
- An open-file check is a snapshot, not a process lock. Stop all writers before marking ready, including child agents. A process that starts later can race cleanup. This tool is for trusted local tasks, not hostile programs running under the same user account.
- If a hook times out, some files can remain. Inspect the directory and retry. The plugin does not assume that file age means a task is complete.
- Cleanup runs at
Stop, before other hooks' continuation decisions are known. Mark files ready only when no later continuation will need them.
Download task-cleaner-v0.1.2.zip and SHA256SUMS from the v0.1.2 release. In the download directory, check and extract the package:
shasum -a 256 -c SHA256SUMS
unzip task-cleaner-v0.1.2.zip
codex plugin marketplace add ./task-cleaner-v0.1.2
codex plugin add task-cleaner@task-cleaner-localKeep the extracted directory in a permanent location. Then start a new chat and trust the hooks as described in Install.
For development, run these commands from the repository root:
codex plugin marketplace add .
codex plugin add task-cleaner@task-cleaner-localAll three methods use the task-cleaner-local marketplace. Choose one method. To change methods, first run codex plugin marketplace remove task-cleaner-local, then add the new source.
python3 -m unittest discover -s tests -vTests cover session separation, retained tasks, preview, repeated events, symbolic links, hard links, replaced directories, invalid identifiers, open-file check failures, and real file removal.
This is a fresh implementation. No source code was copied from these projects:
- CleanMyCodex: selected cleanup and protection for user outputs.
- codex-clean: a small Python helper and cleanup preview.
- codex-cleaner: limited cleanup scope and protection for working files.
The hook contract follows OpenAI Hooks documentation. The package follows OpenAI plugin documentation.