Use XDG Base Directory defaults for Codex configuration
Open 💬 0 comments Opened Jul 23, 2026 by snuffop
Summary
Codex currently defaults its user configuration directory to:
~/.codex/config.toml
On Linux, it should follow the XDG Base Directory Specification and default to:
${XDG_CONFIG_HOME:-$HOME/.config}/codex/config.toml
Rationale
Using the XDG default would:
- keep configuration files under the standard Linux configuration hierarchy;
- avoid adding another application-specific dot-directory directly under
$HOME; - improve consistency with other modern Linux CLI applications;
- make configuration management, backups, and dotfile tooling cleaner;
- respect users who already set
XDG_CONFIG_HOME.
Suggested behavior
- Use
${XDG_CONFIG_HOME}/codex/config.tomlwhenXDG_CONFIG_HOMEis set. - Otherwise use
$HOME/.config/codex/config.toml. - Preserve
CODEX_HOMEas an explicit override for users who need a custom location. - Optionally retain backward compatibility by reading
~/.codex/config.tomlwhen no XDG-path configuration exists, with a migration notice.
Environment
Linux / Arch Linux, but this applies generally to Linux and other XDG-aware Unix environments.
Reference: freedesktop.org XDG Base Directory Specification.