What variant of Codex are you using?

CLI

What feature would you like to see?

Add an @path/to/file.md directive to AGENTS.md that the CLI resolves at instruction-assembly time, inlining referenced file content before sending to the model. This enables modular, maintainable instruction sets - and direct interoperability with Claude Code, which already ships this exact syntax in CLAUDE.md.

The problem

Codex's instruction composition is limited to directory-walk layering: one AGENTS.md per directory level, concatenated root-to-cwd. This creates five concrete problems:

No modular reuse across projects. A developer working across 10+ repos with shared conventions must either duplicate content into each repo's AGENTS.md or maintain a single bloated ~/.codex/AGENTS.md that includes everything regardless of relevance.

No team-level instruction ownership. When different teams own different concerns (frontend style, security policy, deployment conventions), there's no way to split these into independently maintained files composed at load time. Everyone edits one file, merge conflicts ensue, instructions drift.

Cross-tool interoperability gap. Claude Code supports @path/to/file.md imports in CLAUDE.md plus an auto-loaded .claude/rules/ directory. Teams using both tools on the same projects must maintain parallel, divergent instruction files. This undermines AGENTS.md's role as an open cross-tool standard under the Linux Foundation / AAIF.

Dynamic instruction loading is impossible. As raised in #11838, the model cannot reliably follow "read this file next" directives embedded in instruction text - the CLI, not the model, assembles the system prompt. The workaround is shell-side concatenation (cat file1.md file2.md > AGENTS.md), which is fragile and breaks the declarative model.

Context budget waste. Without selective composition, users choose between including everything (wasting context on irrelevant instructions and hitting project_doc_max_bytes truncation) or going without project-specific guidance.

Proposed syntax

# AGENTS.md - project root

@docs/coding-standards.md
@docs/security-policy.md
@~/.codex/instructions/rust-conventions.md

## Project-Specific Instructions

- Use `cargo nextest run` for tests.
- Prefer `tracing` over `log` crate.

Resolution rules

• Relative paths resolve from the directory containing the AGENTS.md
• ~/ resolves to home directory; ~/.codex/ resolves to $CODEX_HOME
• Files inlined in declaration order at the position of the @ line
• Missing files emit a warning to stderr, do not block startup
• Circular includes detected and rejected
• Included content counts against project_doc_max_bytes
• Line must start with @ followed by a file path - no inline usage, no globs

Cross-tool interoperability

With this feature, both tools can reference the same underlying files:

project-root/
  docs/
    coding-standards.md    # shared source of truth
    security-policy.md     # shared source of truth
  AGENTS.md               # @docs/coding-standards.md
  CLAUDE.md               # @docs/coding-standards.md

No duplication, no drift. Same @ syntax, same resolution semantics.

Optional extension: auto-load directory

Lower priority, but a .codex/rules/ directory (analogous to .claude/rules/) where all .md files auto-load alongside AGENTS.md at that directory level would provide zero-configuration composition for teams wanting modular ownership without explicit include lines.

Implementation notes

• Purely a CLI-side text transformation during instruction assembly. No model changes, no API changes.
• The @ prefix for file references is established convention in Claude Code, Cursor .mdc files, and others. Same syntax maximizes cross-tool familiarity.
• Existing project_doc_max_bytes and project_doc_fallback_filenames config keys work as-is. Includes resolve before byte-limit truncation.
• Skills (introduced April 2026) address reusable workflows but not reusable instructions. Complementary, not competing.

Additional information

Related issues

• #11838 - User cannot chain AGENTS.md files; model ignores "read this file next"; requests CLI-level instruction assembly
• #5983 - Requests --bypass-agents + alternative file loading; shell concatenation acknowledged as janky workaround
• #3853 - Enterprise request for centralized MDM-managed instruction files outside user home
• #10067 - Named AGENTS.md variants (--agents review); addresses workflow switching but not modular composition
• #6149 - Requests ability to point Codex to a specific AGENTS.md path
• #3540 - Global preamble_path ignored in interactive sessions

Cross-ecosystem prior art

• Claude Code (production): @path/to/file.md imports in CLAUDE.md, .claude/rules/ auto-load directory
• anthropics/claude-code#13614: Claude Code community requested @include before it shipped - identical pain point
• Cursor: .mdc rule files with frontmatter-based activation and file references
• AGENTS.md spec (agents.md, Linux Foundation / AAIF): positions itself as universal cross-tool standard, but modular composition is not yet part of the spec - this feature would be a natural addition

What this unblocks

• Monorepo teams: shared base instructions with package-level specialization, no duplication
• Multi-tool teams: single source of truth consumed by both Codex and Claude Code
• Enterprise: centralized policy files referenced from any project's AGENTS.md
• Individual developers: language/framework instruction libraries composed per-project
• Open source maintainers: AGENTS.md that references structured docs already in the repo