feat: @include directive for composable AGENTS.md files

Open 💬 9 comments Opened Apr 11, 2026 by ylluminate

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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

View original on GitHub ↗

9 Comments

github-actions[bot] contributor · 3 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#17239

Powered by Codex Action

thebriancurtis · 3 months ago

This probably belongs with AGENTS.md GitHub.

fuyuan-li · 2 months ago

Hi,
I ran into the same issue. For visibility, #6038 has a candidate implementation here: https://github.com/openai/codex/compare/main...MOlechowski:codex:feat/at-include-directives

Is this still the preferred direction for @include support, or would maintainers prefer a smaller initial patch? (I'm happy to work on)

unitedideas · 2 months ago

The @include part looks right. The migration snag is usually not file reuse, it's behavior drift: shared files cut duplication, but hooks, lifecycle rules, per-agent metadata, and local MCP wrappers still diverge.

It might help if the assembled prompt path were inspectable, even through a debug command or stderr summary. Otherwise teams can share source files and still have no quick way to verify that Codex loaded the instruction set they expected.

There is a concrete AGENTS.md / CLAUDE.md migration write-up here, since this is usually where it breaks in practice:
https://bringyour.ai/agents-md-claude-md

olijboyd · 2 months ago

@unitedideas's point on behaviour drift is a good one. I've been building a format converter between AGENTS.md and CLAUDE.md (https://tomevault.io/studio) and the structural layer is the easy bit. The include syntax to flat inline transformation is pretty mechanical. What seems to be tripping people up are the hooks, MCP wrappers, and lifecycle rules like you said that don't have clean equivalents and no amount of "include xyz" guidance is going to fix that.

The inspectable assembled prompt suggestion would have saved me a lot of head-scratching too earlier on. When testing conversions, the main pain was not knowing what actually got loaded versus what you expected. Even a stderr summary of "resolved these files, total X bytes, truncated Y" would help a lot.

The thing I'm less clear on is should this live in the CLI, or does it need to make it into the AGENTS.md spec itself? If it stays Codex-only then the shared source of truth case gets messy. Claude Code would still need to add AGENTS.md support (soon?! lol) before both tools can read the same file with includes working. Has anyone raised this with the AAIF team yet?

saero-robertpaul · 2 months ago

Hitting this same wall in a Codex+Claude monorepo, and the asymmetry you described — CLAUDE.md supports @, AGENTS.md doesn’t — is exactly where the duplication starts.
Until @include lands in Codex, the workaround we use is to keep one source of truth and compile it out to each tool’s preferred shape. xcaffold’s kind: context resource lets you author a single markdown body that renders verbatim to CLAUDE.md and AGENTS.md in one apply step, so the two files can’t drift because they’re regenerated from the same input every time. For shared sub-files that should be @-referenced from CLAUDE.md but inlined into AGENTS.md, the kind: rule resource fans the same source out per-target — Claude keeps its @-imports preserved, Codex gets the content flattened in directly. The choice between inline and referenced is the renderer’s problem, not the author’s.

Docs: context kind and the multi-target compilation guide

Doesn’t replace the spec change you’re asking for, but it stops the dual-maintenance bleeding for mixed-tool repos in the meantime.

caioribeiroclw-pixel · 2 months ago

The @include resolver probably needs one more acceptance criterion beyond "can inline files": make the resolution/fidelity observable.

A minimal shape that would help migrations:

emit a resolved include graph: source file, resolved path, bytes/tokens, and whether it was inlined or left as a reference
fail or warn on missing files, cycles, repo-root escape, and remote/network includes if those are out of scope
preserve enough source-span metadata that a user can answer "which file produced this instruction?"
distinguish structural success from semantic loss. Example: AGENTS.md can inline shared text, but if the shared source came from a Claude workflow that assumes hooks, MCP wrappers, slash commands, or lifecycle events, the compiled Codex target should say "text preserved, behavior not represented"
add a debug command / JSON mode so CI can diff the assembled prompt after dependency or repo layout changes

The important distinction for teams using Codex + Claude isn't just include syntax parity. It's proving that the target got the same contract, or explicitly showing where it didn't.

I've been testing this framing in Pluribus as a small fidelity report for generated AI context files. The useful bit is less the tool and more the output model: represented sections, unsupported sections, target files, warnings, and a next step before calling something portable/universal:
https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/portability-fidelity-report.md

lbzepoqo · 1 month ago

Adding a concrete user-level case for this.

I tried to keep global Codex instructions modular like this:

~/.codex/AGENTS.md:
@/home/ghoti/.codex/RTK.md

Expected:
Codex expands RTK.md into the instruction context at startup.

Actual:
The @ path appears to be passed through as literal text; the agent only sees it if it manually opens the file.

Why it matters:
Claude Code supports @ imports in CLAUDE.md, including absolute paths, so users maintaining both tools need duplicate instruction files or unreliable “read this file” prompts. This makes AGENTS.md less useful as a shared cross-tool instruction layer.

olijboyd · 1 month ago

On the observable-resolution point @unitedideas and @caioribeiroclw-pixel raised, it helps to split fidelity into two halves that fail differently. The structural half is knowable before the model runs: which files resolved, what each contributed in bytes, what got truncated against the size cap, and whether an @ import flattened cleanly or silently dropped. A deterministic pass over the assembled set catches all of it, and it is the half that bites on migration, since the dropped section is usually the guardrail at the end of the file. The semantic half is the hooks, MCP wrappers, and lifecycle rules with no equivalent on the target, and there a converter can only mark "text preserved, behaviour not represented" rather than carry anything across.

We hit this building conversion between AGENTS.md, CLAUDE.md and the rest, and what proved useful was a per-section report (rendered / unsupported / truncated, with the reason and source file beside each) rather than a single verdict. The one thing I would push into the resolver itself is emitting the structural half by default, a stderr or --json summary of resolved files, bytes, and what was dropped, because once it is observable the author can self-correct, and while it is silent every consumer rebuilds the same guesswork. (Disclosure: I work on TomeVault, which does this conversion; happy to share the section-classification we landed on.)