Is it safe to delete Codex’s ~/.codex folder?
- Partly.
~/.codexis the Codex CLI’s home: yourconfig.toml, possibly your login, and every session it has saved. Old session transcripts can go if you won’t resume them; the configuration and login are yours to keep. - What it costs you: a deleted session can’t be resumed or read back. Deleting
auth.jsonsigns you out, and deletingconfig.tomlresets your settings. - Does it come back? New sessions are written as you work. Deleted ones don’t come back, and Codex keeps every session until you archive or delete it.
- SiftMac’s verdict: You decide
1. What it is
OpenAI’s Codex CLI keeps its local state in CODEX_HOME, which is ~/.codex unless you set it elsewhere. OpenAI lists what you may find there:
config.toml: your local configuration.auth.json: your credentials, if Codex stores them in a file rather than the macOS keychain.history.jsonl: the history Codex saves by default.- Other per-user state, such as logs and caches, in folders like
log,cacheandtmp.
Sessions live in sessions, sorted into folders by year, month and day. Each conversation is a rollout-…jsonl file named with its start time and ID, holding the whole exchange, and it’s what codex resume reads to carry on where you left off. Archived sessions are kept in archived_sessions.
2. Where it is
~/.codex
~/.codex/sessions/<year>/<month>/<day>
~/.codex/archived_sessions
If you set the CODEX_HOME environment variable, all of it lives in that folder instead. ~/.codex is hidden in Finder; press ⇧⌘. to show hidden files.
3. How big it gets
A session file holds every message, tool call and command output of that conversation, so long agent runs make big files, and sessions accumulate month after month. history.jsonl grows too unless you cap it. To see where the space is:
du -sh ~/.codex/* 2>/dev/null | sort -h
du -sh ~/.codex/sessions/*/* | sort -h
4. How to delete it safely
Use Codex’s own command. codex delete permanently deletes a saved session by its ID or name, after asking. The ID is the last part of the session file’s name:
codex delete <session>
codex archive is not the same: OpenAI describes it as tidying the session picker without deleting the transcript, so an archived session still takes its space.
Old sessions by hand. With Codex not running, you can move a month’s folder in ~/.codex/sessions to the Trash in Finder once you’re sure you won’t look back at those sessions.
Cap the history file. In config.toml, OpenAI’s documentation shows a size limit for the history, after which Codex drops the oldest entries, or a setting that turns history off:
[history]
max_bytes = 104857600
# or turn it off: persistence = "none"
Leave config.toml and auth.json alone unless you mean to reset Codex or sign out.
5. What happens afterwards
- Deleted sessions disappear from
codex resumeand their transcripts are gone. Archived ones stay on disk until you delete them. - Codex works as before and writes new sessions as you go, so the folder grows again.
- If you removed
auth.json, Codex asks you to sign in again; withoutconfig.toml, every setting is back at its default. - Logs and caches are written again as Codex needs them.
Questions
Does archiving a Codex session free space?
No. Archiving hides a session from the picker and keeps the transcript. Use codex delete to remove it.
Is it safe to delete ~/.codex/log?
Yes, with Codex quit. Those are Codex’s own logs, and it writes new ones as it runs.
Will deleting ~/.codex sign me out?
If your login is stored in auth.json, yes. Codex can keep it in the macOS keychain instead, in which case the file isn’t there.
Where does Codex store sessions on a Mac?
In ~/.codex/sessions, in folders by year, month and day, one .jsonl file per session, with archived sessions in ~/.codex/archived_sessions.
How SiftMac handles it. Its AI files category lists Codex session files in ~/.codex/sessions and archived_sessions that haven’t changed for the window you set (30 days by default); they’re You decide and wait on the Undo Shelf for 7 days. It also clears Codex’s cache and tmp folders while Codex isn’t running, and never touches config.toml or auth.json.
Download SiftMac · scanning is free, and so is your first 2 GB of cleaning · See how it works