Where apps hide your files

Locating Codex's config.toml

Updated 2026-10-28 · 5 min read

Codex CLI stores its configuration, sessions and logs in a hidden .codex folder in your home directory. You can open it, edit config.toml, and see what takes the space without touching your sign-in files.

The location

Codex CLI keeps its configuration in a hidden folder in your home directory:

~/.codex/config.toml

That is the user-level config file, per OpenAI's Codex documentation. The folder name starts with a dot, so Finder hides it. Open it with Go > Go to Folder (⇧⌘G), paste ~/.codex and press Return, or from Terminal:

open ~/.codex

If you cannot see config.toml, it may simply not exist yet. Codex runs without one, and you create it when you first change a setting.

Which config file wins

Codex reads settings in layers. The documented locations are:

File	Applies to
~/.codex/config.toml	You, in every project.
<project>/.codex/config.toml	One repository. Codex loads project .codex/ layers only for projects you have trusted.
/etc/codex/config.toml	Every user on the machine (the documented system-level file on Unix).
~/.codex/<name>.config.toml	A profile, used only when you start Codex with --profile <name>. It ranks above your user file and below project files.

A project file in a repository you have not trusted is ignored, which is the usual reason a project setting appears to do nothing.

The documentation also says Codex stores its local state under CODEX_HOME, which defaults to ~/.codex. If echo $CODEX_HOME prints a path, Codex is using that folder instead, and everything in this guide lives there.

What else is in ~/.codex

~/.codex is more than a config file. On the Mac used for this guide it held the following (names, sizes and permissions only were inspected):

Item	What it is
config.toml	Your settings. Plain text, safe to edit with the app closed.
auth.json	Sign-in credentials, with permissions that only your user can read. Never share or paste it.
history.jsonl	Your prompt history, also readable only by you.
sessions/	One file per session, filed as sessions/<year>/<month>/<day>/rollout-<date>T<time>-<id>.jsonl.
logs_2.sqlite	A log database. The number in the name can change between versions.
skills/	Skills you installed.
rules/	Rules files, such as default.rules.
packages/	Installed Codex runtimes. Here packages/standalone held the Codex CLI itself, and ~/.local/bin/codex links into it.
plugins/	Plugin data; only a cache folder on this Mac.
version.json, installation_id	Small bookkeeping files.

Two things to know. Per the documentation, auth.json appears only when credentials are stored in a file, and otherwise they go in the macOS keychain, so its absence is normal. And history.jsonl appears only while history persistence is on, which is the default; the docs say you can turn it off with persistence = "none" under a [history] table, or cap its size with max_bytes.

Editing the file

Open it in any plain-text editor:

open -t ~/.codex/config.toml

The format is TOML: key = "value" lines, with [section] headings for groups such as [history]. Quote strings, and do not use smart quotes from a word processor. Start a new Codex session after a change to be sure it is picked up.

A broken file usually shows as a parse error at startup. Fix the line it points to, or move the file aside to start clean and add settings back one at a time.

Seeing what takes the space

Codex can grow large. On the Mac used for this guide ~/.codex was about 4.2 GB, and most of that was packages/ (about 3.1 GB), then sessions/ (about 0.4 GB) and plugins/ (about 0.3 GB). To check yours without opening anything:

du -sh ~/.codex/* | sort -h | tail

Session files are your conversation records, so deleting them loses the ability to resume or review those sessions. Move old year or month folders under sessions/ to the Trash in Finder with Codex quit, if you are sure. Leave config.toml, auth.json and rules/ alone unless you mean to reset them. Do not clear packages/ to save space: on this Mac it holds the installed CLI, so removing it removes Codex until you reinstall. plugins/cache is a cache, but check Codex's documentation before removing it by hand.

The desktop app shares this folder

Since July 2026 the ChatGPT desktop app has been built from OpenAI's Codex app (bundle identifier com.openai.codex). On the Mac used for this guide it works in the same ~/.codex folder the CLI uses by default, so treat changes there as shared. OpenAI's docs also say the CLI and the IDE extension share the same configuration layers. The app's own caches and logs are separate, in ~/Library/Application Support/Codex, ~/Library/Caches/Codex and ~/Library/Logs/com.openai.codex.

Backing up and moving to a new Mac

Copy config.toml, rules/ and skills/ to the same place on the new Mac. Sign in again there instead of copying auth.json, since it holds credentials. Time Machine includes dot-folders by default, so the whole of ~/.codex is backed up unless you excluded it. Excluding packages/ is reasonable, since reinstalling Codex recreates it.

If your config sits in a dotfiles repository, check it contains no keys or tokens before you commit it. Keep auth.json out of any repository.

Why search misses these files

Spotlight and Finder searches leave out hidden folders such as ~/.codex, so a search for "config" will not show it. Terminal finds it directly:

ls -la ~/.codex

Finding it again later

Typing config.toml into Everywhere lists every copy on the Mac, which separates your ~/.codex file from project-level .codex ones inside repositories (those in Documents or Desktop appear once Everywhere has Full Disk Access). Typing rollout- lists your session files, since their names start that way. It matches names only, so it will not show which session contains what. Press ⌘T on a result to open a Terminal in that folder.

Common questions

Where is the Codex config.toml on a Mac?

At ~/.codex/config.toml. The folder is hidden, so open it with Go to Folder (⇧⌘G) or open ~/.codex. If the file is missing, create it; Codex works without one.

Can I set Codex config per project?

Yes. Put a .codex/config.toml in the repository. Codex loads project layers only for projects you have trusted.

What is CODEX_HOME?

The environment variable that sets where Codex keeps its local state. It defaults to ~/.codex, so if it is set, your config folder is wherever it points.

Is it safe to delete files in ~/.codex?

Only some. Old session files can go with Codex quit, but config.toml, auth.json and rules/ hold your settings and sign-in, and packages/ can hold the Codex install itself, so leave those unless you want a reset.