What is the ~/.codex folder on Mac? Can you delete it?

Where it is

What it is

Codex, OpenAI's coding agent, stores its per-user data in ~/.codex. The configuration is in config.toml, your sign-in is in auth.json, and any global instructions you wrote are in AGENTS.md.

The part that grows is the record of your work. The sessions folder keeps a file for each session, organised by date, and history and log files sit alongside it. Depending on how you use Codex, the folder can also hold plugins, downloaded packages and a worktrees folder with working copies of your repositories.

Apart from worktrees, nothing here is needed by your projects. The folder is only used by Codex itself.

How big it gets

Usually tens to hundreds of MB, and more after long use, since old sessions are kept.

How to clear it by hand

1. Run the command below to see which parts are largest. It only reads sizes.
2. Close any running Codex sessions and quit the Codex app.
3. Open ~/.codex/sessions in Finder and move the older dated folders to the Trash.
4. If there is a worktrees folder, treat it as your work. Check each working copy for changes you have not merged, and remove only the ones you are sure are finished.
5. Keep config.toml, auth.json and AGENTS.md. Treat auth.json as a secret and do not share or upload it.

du -sh ~/.codex/* | sort -hr | head -15

What happens afterwards

Sessions you removed can no longer be resumed. A removed worktree takes any unmerged changes with it. If you delete auth.json or the whole folder, you sign in again and Codex returns to its default configuration.

How Diskzy handles it

Diskzy shows ~/.codex on the disk map with the size of each subfolder, and Search can list its largest or oldest files. Anything you remove with Diskzy goes to the Trash first.

Related guides

• .claude~/.claude
• Cursor~/Library/Application Support/Cursor
• .cache~/.cache