Skip to main content
Watch: I Built an AI App Without Leaving Databricks

Codex CLI reference - Config files

Codex CLI config files and locations

Codex CLI documents 18 config files, including ~/.codex/config.toml, .codex/config.toml and $CODEX_HOME/profile-name.config.toml. These are the files and directories Codex CLI reads its configuration from. Each row gives the docs' description, accepted values and an example where one is documented.

Last verified 7 official pagesFull Codex CLI reference

Codex CLI config files
PathDescriptionExample
~/.codex/config.toml

User-level configuration file; personal defaults live here. Precedence is below CLI flags, project config, and profile files.

Docs: ~/.codex/config.toml		-no example
.codex/config.toml

Project-scoped config overrides; Codex walks from the project root to the working directory and the closest file wins. Loaded only when the project is trusted.

Docs: .codex/config.toml		-no example
$CODEX_HOME/profile-name.config.toml

Profile file layered on top of the base user config when you pass --profile profile-name. Use top-level keys, not [profiles.profile-name] (no longer read in Codex 0.134.0 and later).

Docs: $CODEX_HOME/profile-name.config.toml
codex --profile deep-review
/etc/codex/config.toml

System config on Unix (if present); ranks below user config and cloud-managed defaults, above built-in defaults.

Docs: /etc/codex/config.toml		-no example
requirements.toml

Admin-enforced configuration file that constrains security-sensitive settings users cannot override.

Docs: requirements.toml		-no example
$CODEX_HOME/auth.json

Stores credentials when you use file-based credential storage (otherwise the OS keychain/keyring is used).

Docs: $CODEX_HOME/auth.json		-no example
~/.codex/history.jsonl

Local session transcript history under CODEX_HOME when history persistence is enabled; configure with [history].

Docs: ~/.codex/history.jsonl		-no example
~/.codex/hooks.json

User-level lifecycle hooks file; hooks can also be defined inline as [hooks] tables in config.toml.

Docs: ~/.codex/hooks.json		-no example
<repo>/.codex/hooks.json

Project-local lifecycle hooks; load only when the project .codex/ layer is trusted.

Docs: <repo>/.codex/hooks.json		-no example
~/.codex/AGENTS.md

Global guidance file in the Codex home directory, read before any work and inherited by every repository.

Docs: ~/.codex/AGENTS.md		-no example
~/.codex/AGENTS.override.md

Temporary global override read instead of ~/.codex/AGENTS.md when it exists; remove it to restore the shared guidance.

Docs: ~/.codex/AGENTS.override.md		-no example
AGENTS.md

Project instructions file; Codex walks from the project root to the working directory and includes at most one file per directory, checking AGENTS.override.md, then AGENTS.md, then project_doc_fallback_filenames. Combined size is capped by project_doc_max_bytes (32 KiB by default).

Docs: AGENTS.md		-no example
AGENTS.override.md

Per-directory override checked before AGENTS.md; when present, the AGENTS.md in the same directory is ignored.

Docs: AGENTS.override.md		-no example
~/.codex/rules/default.rules

User-layer execpolicy rules file (Starlark prefix_rule() entries). Codex writes here when you add a command to the allow list in the TUI.

Docs: ~/.codex/rules/default.rules		-no example
<repo>/.codex/rules/

Project-local .rules files; load only when the project .codex/ layer is trusted. Codex scans rules/ under every active config layer at startup.

Docs: <repo>/.codex/rules/		-no example
$CODEX_HOME/themes

Place a .tmTheme file here to add a custom syntax theme selectable from /theme.

Docs: $CODEX_HOME/themes		-no example
codex-tui.log

Opt-in plaintext TUI log written to the directory set by log_dir.

Docs: codex-tui.log
codex -c log_dir=./.codex-log
CODEX_HOME/packages/standalone

Standalone package cache used by the standalone installer.

Docs: CODEX_HOME/packages/standalone		-no example

The rest of the Codex CLI reference

FAQ

How many config files does Codex CLI have?

The official Codex CLI docs list 18 config files, including ~/.codex/config.toml, .codex/config.toml and $CODEX_HOME/profile-name.config.toml. All of them are in the table above, in the docs' order.

What does ~/.codex/config.toml do in Codex CLI?

User-level configuration file; personal defaults live here. Precedence is below CLI flags, project config, and profile files.

Where are Codex CLI config files documented?

On 7 official docs pages at learn.chatgpt.com, last read on October 17, 2026. Every row in the table links the exact section it came from.

More on Codex CLI

Use other models in Codex CLI

Setup guides from the model-in-tool directory, each with the env vars and base URL from official docs.

Sources

Last verified . Names and examples are copied verbatim from the 7 official pages below, and every row above links the exact section it came from.

Newsletter

Know when your tools change

One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.