›_ Codex Issues
Codex Issues / #11301

Use codex.toml (or configurable filename) instead of generic config.toml

Resolved 💬 4 comments Opened Feb 10, 2026 by PaulRBerg Closed Feb 14, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI (also affects shared config behavior used by IDE/App)

What feature would you like to see?

I’d like Codex to stop using the generic filename config.toml and move to a clearer Codex-specific name: codex.toml.

Today, project-scoped config lives in .codex/config.toml and user config in ~/.codex/config.toml. The filename is very generic and easy to confuse with other tools, especially in repos that already contain multiple config.toml files.

Proposed direction:

  1. Prefer codex.toml as the canonical config filename.
  2. Support existing config.toml during a transition window.
  3. Emit a non-blocking warning when loading config.toml if codex.toml is absent.
  4. Eventually deprecate config.toml (or keep as fallback indefinitely if needed).

Possible resolution paths:

  • Minimal change: keep directories as-is, just rename filenames:
  • ~/.codex/config.toml -> ~/.codex/codex.toml
  • .codex/config.toml -> .codex/codex.toml
  • Better long-term flexibility: add a configurable config filename/path override (this may overlap with #7971).

Why this helps:

  • Better discoverability: codex.toml is self-identifying.
  • Fewer naming collisions/confusion with other tools.
  • Easier onboarding and docs readability (users instantly know the file belongs to Codex).

Additional information

I saw #7971 (config path configurability) was completed, which is related, but this request is specifically about the default filename semantics and discoverability.

Environment (for context):

  • Codex CLI: 0.98.0
  • Platform: macOS v26.2

View original on GitHub ↗

4 Comments

etraut-openai contributor · 6 months ago

Thanks for the suggestion, but I think it's unlikely that we'd switch this.

I'll leave the feature request open for a little while to see if it gets additional support from the community, but we'll likely pass on this.

PaulRBerg · 6 months ago

thx for the quick reply @etraut-openai

that's understandable.

Another advantage of codex.toml would be better marketing for Codex CLI

PaulRBerg · 6 months ago

@Ashutosh0x I've already written the proposal. please update your comment; it doesn't make sense to write another proposal in this issue thread

Ashutosh0x contributor · 6 months ago

Proposal: Support codex.toml as Configuration File

Context: This proposal corresponds to the previously closed openai/codex#11441 and Closes #11301. It introduces support for codex.toml as the primary configuration filename.

Problem Analysis (What & Why?)
Currently, Codex uses config.toml for its settings. To better align with project branding and modern project-specific configuration patterns (like cargo.toml or gh-actions.yml), we want to transition to codex.toml. This change must be non-breaking for existing users while encouraging new users to adopt the new standard.

Proposed Solution (How?)
The implementation provides a transparent migration path:

  1. Filename Priority: Added CODEX_TOML_FILE constant. The configuration loader now checks for codex.toml first. If not found, it falls back to config.toml.
  2. System & User Layers: Updated config_loader/mod.rs to apply this priority across all configuration layers (System, User, and Project).
  3. Persistence Support: Modified ConfigService to ensure that when a user updates their configuration via the CLI or API, the changes are written back to the existing file (whether codex.toml or config.toml). If neither exists, it defaults to creating codex.toml.
  4. CLI Integration: Updated apply_blocking in config/edit.rs to respect the new filename priority during manual edits.

Verification:

  • Verified that existing config.toml files are correctly loaded.
  • Verified that new configurations prioritize codex.toml.
  • Ensured all configuration tests pass with the new multi-filename support logic.

Note: My previous comment was a proposal summary, not a new proposal. I've updated it here for clarity.