Identify the exact Codex client and version before reviewing disk usage. CLI data, desktop application data, IDE data and project worktrees have different owners. A folder name or an old cleanup list is not evidence that its contents are disposable.
Separate storage from cache
- Configuration and authentication: keep settings, credentials and account state.
- Sessions and worktrees: keep conversation records and source changes. A worktree is a working copy, not a cache.
- Diagnostics: retain logs needed to investigate a problem; review individual closed files only after confirming ownership.
- Unknown directories: leave them unchanged until the current client documentation or a reproducible test establishes their purpose.
Documented configuration: keep these files
Codex uses ~/.codex/config.toml for personal settings and .codex/config.toml for project settings. These are configuration, not disposable cache. Preserve them during disk cleanup. A project-local .codex/ directory must not be selected as a whole.
Source: OpenAI Codex configuration documentation, reviewed September 23, 2026. This documents the files' purpose; it is not a deletion test or a complete inventory for the desktop app.
Inspect before cleanup
- Finish or save active work and quit the relevant client normally.
- Use Finder Get Info to measure the specific folder you own. Do not treat all of Library, the system temporary directory or a project directory as Codex cache.
- Back up anything needed for recovery. Do not remove a directory merely because its name includes OpenAI, Codex, cache or tmp.
- For a file whose regenerable purpose is confirmed, review it individually and use Trash. Keep it there until you have checked normal startup, authentication, session history and project changes.
- If state is missing, stop cleanup, quit the client and restore the original file to its original location. Do not overwrite newly created files without preserving both versions.
Evidence limitation: this revision removes unverified generic path and deletion recommendations. It does not claim a tested path list for every Codex version. Inspect the installed client's storage documentation before selecting files.
AI Agent Clean workflow
Use AI Agent Clean to preview supported data categories. Inspect each item’s path, category, size and selection before confirming an action. A detected item is not automatically disposable; available categories depend on the installed build and granted folder access.
- Choose the specific folders you want to scan when prompted (macOS 14+).
- Run AI Agent Clean or full Smart Scan from the Mac cleaner module.
- Expand the available results and uncheck configuration, credentials, sessions, project data and anything whose purpose is uncertain.
- For confirmed disposable items, use the available Trash action and check normal operation before emptying Trash. Trash is not a backup, and recovery after permanent removal is not guaranteed.
- Never delete
.env, API key files, or project directories while hunting caches. - Some SQLite files mix cache and session state — prefer category-based cleanup over blind folder delete.
- Logs may contain file paths from your machine; treat archived logs as sensitive.
- Do not use
sudo rm -rfon Library paths — user-level Trash is sufficient. - A symbolic link may point outside the folder you are inspecting. Leave it unchanged unless you understand both the link and its target; this guide does not certify link handling for every app build.
Permissions and versions
Review only locations you are authorized to access. Grant access to the specific folders requested by your installed cleaner; permissions do not prove a file is disposable. Record your client version when investigating changed storage behavior.
How much space can you recover?
The recoverable amount depends on logging settings, run frequency, and Codex version — measure before and after on your own Mac. Pair Codex cleanup with finding disk space on Mac using Space Lens to measure neighboring large folders like Docker or Xcode.
FAQ
Where does Codex store cache and logs on Mac?
Locations depend on the exact client and its configuration. This guide does not classify a whole Library folder, project folder or hidden client directory as disposable cache.
Is clearing Codex cache safe?
Only review files whose purpose and owner you have confirmed. Keep authentication, configuration, sessions and project data; use Trash for confirmed disposable files and verify recovery before permanent removal.
Should I delete project .env files?
No. Never delete .env, API keys, or source while hunting caches. Stick to labeled cache/log categories in AI Agent Cleaner.
Retain logs according to their purpose
There is no universal monthly deletion schedule in this guide. Keep diagnostics needed for active issues and follow the installed client’s documented retention settings. If you archive a confirmed log, protect sensitive paths and credentials, verify the archive, and review whether the original is still needed before removing it.
Do not change system logging or use administrator deletion commands to follow this guide. This article does not provide a tested inventory of diagnostic files or a version-specific log rotation procedure.
Project-level temp files
Project-local directories may contain instructions and configuration. In particular, do not classify .codex/ as a temporary directory. Inspect project storage separately and review the installed tool’s supported locations. Never delete .git or lockfiles when chasing temp caches.