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

  1. Use ${XDG_CONFIG_HOME}/codex/config.toml when XDG_CONFIG_HOME is set.
  2. Otherwise use $HOME/.config/codex/config.toml.
  3. Preserve CODEX_HOME as an explicit override for users who need a custom location.
  4. Optionally retain backward compatibility by reading ~/.codex/config.toml when 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.

View original on GitHub ↗