Configuration Precedence Order in Codex Plugin: User-Level vs. Project-Level `.codex/config.toml`

Configuration settings are resolved in a two-layer precedence chain: user-level ~/.codex/config.toml is loaded first, then project-level .codex/config.toml overrides those values if the project is trusted.

The openai/codex-plugin-cc repository implements a predictable configuration hierarchy that balances personal defaults with project-specific requirements. Understanding this precedence order ensures you know exactly which settings apply when working across multiple repositories.

How Configuration Files Are Loaded

The Codex plugin resolves configuration through a sequential merge process defined in plugins/codex/scripts/lib/codex.mjs. This loader implements two distinct tiers:

1. User-level config – ~/.codex/config.toml serves as the foundation
2. Project-level overrides – .codex/config.toml in the current project root merges on top, but only when the project is trusted

This design lets developers maintain consistent personal preferences while allowing repositories to enforce project-specific requirements.

Precedence Rules in Detail

User-Level Configuration: The Default Layer

The user-level file at ~/.codex/config.toml establishes baseline settings for all Codex interactions. This file is typically generated by the Codex CLI and contains your preferred defaults:

# ~/.codex/config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

These values apply universally unless a trusted project specifies alternatives.

Project-Level Configuration: The Override Layer

When working in a trusted repository, the loader checks for .codex/config.toml in the project root (the directory where Codex was started). According to the README § Common Configurations (lines 80-85), this file merges last and takes precedence:

# .codex/config.toml (project-level, overrides user-level)

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

The resulting effective configuration for model_reasoning_effort becomes "high"—the project value wins.

Trust Verification Gates Project Overrides

A critical condition in the precedence chain is project trust status. The loader in plugins/codex/scripts/lib/codex.mjs only applies project-level overrides when the repository is explicitly trusted. Untrusted projects fall back entirely to user-level configuration, preventing potentially malicious project configs from executing automatically.

Practical Configuration Management

To leverage this precedence order effectively:

• Store personal preferences in ~/.codex/config.toml (preferred models, default reasoning effort)
• Place project requirements in repo-root .codex/config.toml (specific model versions, team-standard settings)
• Verify trust status when project overrides aren't applying as expected

Summary

• User-level ~/.codex/config.toml loads first as the default configuration layer
• Project-level .codex/config.toml merges second and overrides matching keys
• Trust verification is required for project-level overrides to take effect
• The loader implementation resides in plugins/codex/scripts/lib/codex.mjs
• Precedence behavior is documented in README.md, lines 80-85

Frequently Asked Questions

What happens if a project is not trusted?

The loader skips the project-level .codex/config.toml entirely. Only user-level settings apply, ensuring untrusted code cannot silently modify your Codex configuration.

Can I disable project-level overrides for specific settings?

No selective disable mechanism exists. To prevent project overrides for a setting, ensure it is not defined in the project's .codex/config.toml file, or work with the repository untrusted.

Where does the configuration loader prioritize environment variables?

Environment variables are not mentioned in the current precedence chain described in the source. The documented resolution order covers only TOML file sources: user-level first, then conditional project-level merge.

Does the order of keys within a config file affect precedence?

No. Within each configuration file, key order is irrelevant. Precedence is determined entirely by which file provides the value, not by declaration sequence.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}