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

Open 💬 1 comment Opened May 21, 2026 by ajjuaire

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:

| Pain | Why it matters |
|---|---|
| Hard to edit | Find-the-right-section-in-a-1000-line-file every time |
| Hard to share | Can't easily commit a single rule to a dotfiles repo or share one file with a teammate |
| Hard to disable temporarily | No way to "turn off the rules for this session" without editing the file |
| Hard to source-of-truth | Many users already maintain ~/.claude/rules/*.md and want Codex to read the same files |
| Hard to review diffs | A change to one rule produces a diff in a giant file, mixed with unrelated content |
| Hard to template | Teams want to ship specific rule files (e.g. a my-team-rules.md) without overwriting a user's whole AGENTS.md |

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

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗