Allow profiles to override the global AGENTS.md path

What variant of Codex are you using?

cli

What feature would you like to see?

Problem

Codex currently builds an instruction chain by loading global guidance from $CODEX_HOME/AGENTS.override.md or $CODEX_HOME/AGENTS.md, followed by applicable project-level AGENTS.md files.

There is no supported configuration option that lets a selected profile choose a different global instruction file or disable global instructions.

I regularly use Codex in two different situations:

• In my own projects, a comprehensive AGENTS.md is checked into the repository for portability and consistency across developers and environments. These projects do not need my global instructions.
• When contributing to third-party or open-source projects, I want Codex to load my global working rules because those repositories generally do not contain them.

Loading both sets can duplicate instructions, introduce conflicting guidance, and consume instruction/context capacity unnecessarily. This is especially relevant because the combined instruction chain is limited by project_doc_max_bytes, which defaults to 32 KiB.

See the current AGENTS.md discovery behavior.

Current workarounds include:

• Renaming the global AGENTS.md before starting Codex.
• Creating and removing AGENTS.override.md.
• Maintaining separate CODEX_HOME directories.
• Using a wrapper script that manipulates files before launching Codex.

These workarounds either modify shared state or affect more than instruction selection.

Proposal

Add a profile-aware configuration option that selects the global instruction file:

global_agents_file = "AGENTS.common.md"

The option should also support explicitly disabling global instructions:

global_agents_file = false

The exact option name and representation are illustrative. The important behavior is that profiles can select or disable the global instruction source.

Primary use case

Profiles could distinguish projects that need global defaults from projects that provide complete instructions themselves:

# ~/.codex/global-defaults.config.toml
global_agents_file = "AGENTS.common.md"

# ~/.codex/project-only.config.toml
global_agents_file = false

Usage:

# Load personal global guidance plus project instructions
codex --profile global-defaults

# Load only project instructions
codex --profile project-only

Additional use cases

The same option would allow profiles to select role-specific global instructions.

For example:

# ~/.codex/reviewer.config.toml
global_agents_file = "AGENTS.reviewer.md"

# ~/.codex/auditor.config.toml
global_agents_file = "AGENTS.auditor.md"

# ~/.codex/implementer.config.toml
global_agents_file = "AGENTS.implementer.md"

Usage:

codex --profile reviewer
codex --profile auditor
codex --profile implementer

Each profile could combine its instruction file with other settings appropriate to that working mode, such as the model, reasoning effort, approval policy, or sandbox configuration.

Suggested semantics

• When the option is unset, preserve the current global discovery behavior.
• When it contains a path, use that file instead of the normal global AGENTS.override.md / AGENTS.md lookup.
• When set to false, skip global instruction discovery entirely.
• Continue discovering and loading project-level instruction files normally.
• Resolve relative paths against CODEX_HOME; also allow absolute paths.
• Apply the value after loading the selected profile so profile configuration can override the base user configuration.
• Restrict the option to user configuration, profile configuration, and explicit CLI overrides. Project-local configuration should not be able to select arbitrary user files or silently disable personal guidance.
• Report a clear error when an explicitly configured file does not exist or cannot be read instead of silently falling back.
• Include the selected global instruction source, or its disabled state, in relevant diagnostics such as /status.

Why profiles?

Codex profiles already represent named configuration layers selected through --profile.

Instruction selection fits naturally into that model because it is often part of a broader working mode. For example, an auditor profile might select audit-specific instructions together with stricter permissions and greater reasoning effort.

Using profiles would:

• Reuse the existing configuration-layer mechanism.
• Keep instruction selection composable with other settings.
• Avoid switching CODEX_HOME.
• Avoid renaming or temporarily replacing files.
• Avoid introducing a separate CLI-only concept.
• Leave project-level AGENTS.md discovery unchanged.

Related issues

• #10067 - Add --agents flag to switch between named AGENTS.md variants proposes broader named-variant discovery at both global and project levels. This request is narrower: allow existing configuration profiles to select or disable only the global instruction source.
• #21546 - Add --agents-file or --instructions-file option for explicit AGENTS.md path selection requested an explicit CLI path. This proposal makes the selection persistent and composable through profiles.
• #38680 - Add config.toml option for explicit additional AGENTS.md paths requests additive instruction paths. This proposal instead replaces or disables the existing global instruction source.

Acceptance criteria

• A profile can select a specific global instruction file.
• A profile can disable global instructions entirely.
• Project-level AGENTS.md discovery continues to work in both cases.
• Running Codex without the option preserves current behavior.
• Missing or unreadable explicitly configured files produce a clear diagnostic.
• Codex exposes which global instruction source was selected.

Additional information

No response

Begin at the --profile configuration path and current global AGENTS.md discovery behavior, including CODEX_HOME and project-level AGENTS.md loading. Trace how profile values could select or disable the global source, then verify the acceptance criteria: unchanged defaults, working project discovery, clear missing-file diagnostics, and visibility in /status.