codex - 💡(How to fix) Fix feat: auto-load all `.md` files from `~/.codex/instructions/` (modular companion to `~/.codex/AGENTS.md`)

What variant of Codex are you using?

CLI

What feature would you like to see?

Codex already supports a global ~/.codex/AGENTS.md for user-level instructions. Add a directory ~/.codex/instructions/ whose .md files are auto-loaded and concatenated alongside it — so users can keep their global ruleset as modular files instead of one monolithic blob.

Equivalent to Claude Code's ~/.claude/rules/ directory.

The problem: one big blob

~/.codex/AGENTS.md works, but it's a single file. Real users accumulate global rules across distinct, unrelated topics:

• guardrails
• internal-tooling context (build systems, code review, deployment, ticketing)
• team-specific rules
• privacy

Cramming all of that into one AGENTS.md is painful:

developer_instructions in config.toml has the same shape — it's a single inline string, also one big blob, and worse: it has no file variant (developer_instructions_file does not exist).

Proposed solution: a modular instructions directory

~/.codex/instructions/
  00-guardrails.md
  10-internal-tooling.md
  20-team-specifics.md
  30-privacy.md

Behavior:

• Every .md file is loaded automatically — no config changes required
• Files are concatenated in lexical order (use 00-, 10- prefixes for explicit ordering)
• The result is appended to whatever ~/.codex/AGENTS.md already contributes (or merged in a documented order)
• Empty/missing directory is a no-op
• Each file's content can carry a small header (# Guardrails) so the model sees clean section boundaries

Why a directory beats a bigger AGENTS.md

• Modularity: each topic is its own file with a purpose-conveying name
• Composable distribution: a team can drop in a single guardrails.md without touching the user's other rules
• Version control–friendly: per-rule diffs, per-rule blame, per-rule history
• Symlink-friendly: ln -s ~/.claude/rules/foo.md ~/.codex/instructions/foo.md lets users share rules across agents without duplication
• Easy to disable a rule: rename to .md.off or move out of the directory — no edit-then-re-edit cycle
• Familiar: matches ~/.claude/rules/ (Claude Code), .cursor/rules/ (Cursor), and the .codex/rules/ proposal in #17401

Are you interested in implementing this feature?

Yes — happy to provide detailed requirements and test cases.

Additional information

Related issues

• #17401 — @include directive for composable AGENTS.md files (proposes .codex/rules/ auto-load directory — same modularity motivation, project-scoped instead of user-scoped)
• #3853 — Support global/centralized instructions/AGENTS.md + configuration (open since Sep 2025)
• #3540 — Global preamble_path ignored in interactive sessions (closed)

Future extension (out of scope for this issue)

The same directory-loading mechanism could later be extended to enterprise requirements.toml using the existing managed_dir pattern (analogous to managed hooks):

[instructions]
managed_dir = "/enterprise/instructions"
windows_managed_dir = 'C:\enterprise\instructions'

Mentioned only for context — the primary ask in this issue is the user-level directory.

Docs reviewed

• https://developers.openai.com/codex/config-reference
• https://developers.openai.com/codex/config-basic
• https://developers.openai.com/codex/config-advanced