›_ Codex Issues
Codex Issues / #12115

Dynamically loading nested AGENTS.md

Open 💬 23 comments Opened Feb 18, 2026 by kszlim
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Tracker summary

Codex should make nested AGENTS.md behavior easier to understand and debug, especially when deeper files are expected to override shallower repo-level guidance.

Customer signal

  • Customer: Wix
  • Submitted by: Andrew Ginns
  • Source: #codex-feedback, 2026-05-05 05:15 PDT

Evidence

Wix reported issues with nested AGENTS.md behavior and referenced GitHub issue openai/codex#12115. The source question asks whether deeper AGENTS.md files should override shallower ones and whether the current issue is a UX/documentation gap around explaining what happens.

Rollup rule

Track nested AGENTS.md precedence and explanation here. Broader rollout-playbook and rules guidance remains in CEF-65.

Affected accounts

  • Stripe LLC - 1 structured evidence item; highest priority: Must have; latest source: 2026-07-13

Capture notes

  • Existing unstructured issue context also mentions Wix, Clay, and public GitHub discussion on openai/codex#12115.
  • Related CEF issue: CEF-650 tracks Stripe's broader path/glob-aware scoped-rules request.

Issue metadata

{
  "schema_version": "codex_voc_issue_v2",
  "canonical_problem_summary": "Codex should officially load nested AGENTS.md files on demand as work moves into deeper subtrees from repo-root sessions, with deterministic deeper-over-shallower instruction behavior and visibility into active instruction files.",
  "issue_kind": "Product feedback",
  "feedback_theme_l1": "product_surface_capabilities",
  "feedback_theme_l2": "codex_workflow_gaps",
  "secondary_themes": [],
  "affected_accounts": ["Stripe LLC"],
  "triage_flags": ["Duplicate candidate"]
}

View original on GitHub ↗

23 Comments

github-actions[bot] contributor · 5 months ago

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

  • ##11838

Powered by Codex Action

kszlim · 5 months ago

I don't believe the linked issue is a duplicate, it has some overlap, but this is more of a feature request.

miraclebakelaser contributor · 5 months ago

+10 to this. This sort of auto context hydration is a low-hanging fruit for improving agent perf. Launching codex from within subdirectories is a suboptimal solution to this because it means arbitrarily walling off work on different parts of the same repo into separate projects/environments.

It's also part of the AGENTS.md standard:

4. Large monorepo? Use nested AGENTS.md files for subprojects

Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.

--

I think this is a much more natural workflow, though it might come at the expense of some context.

It's the opposite, it affords you more context bc it reduces the need for a monolithic root AGENTS.md.

foontinz · 5 months ago
  • on this feature
Lewiatan · 4 months ago

+1 on this

amit-mittal · 4 months ago

Until this feature is implemented, we have added below in our AGENTS.md and it seems to be working fairly well. 

## Enhancing Context
- Before doing or planning changes under `go/` directory, always load `gocode/AGENTS.md`.
- Before doing or planning changes under `python/` directory, always load `python/AGENTS.md`.
- If there are any other `AGENTS.md` in any of the parent directories of the relevant files, load them in the context too.
amakarenko-sumy · 3 months ago

+1 on this

MuhammedAlkhudiry · 3 months ago

temporary fix add to global AGENTS.md

In a monorepo, if the work include one repo or package or more, read its nested `AGENTS.md`.
ericchernuka · 3 months ago

Having native support for this that matches the behaviour of Claude would be a great way to align the behaviours across our teams.

petroslamb · 2 months ago

What is the design decision against this feature? I only see thumbs up, should be scheduled then.

petroslamb · 2 months ago
temporary fix add to global AGENTS.md `` In a monorepo, if the work include one repo or package or more, read its nested AGENTS.md. ``

These type of workarounds are not enforced, is there a programmatic workaround?

Lewiatan · 2 months ago

TBH for me the best workaround for this was to move to OpenCode 😅

diogogallo · 2 months ago

+1 on this

thomynyk · 2 months ago

+1 on this

xuanswe · 2 months ago

Today, starting to use codex and have this issue. Back to claude code, opencode and wait.

kkshinkai · 2 months ago

I think this feature request has far fewer upvotes than it deserves because many people simply do not realize that they even have to request something this basic.

unitedideas · 2 months ago

One practical workaround until native loading exists is to make nested instruction discovery an explicit audit step, not just a prose convention in the root AGENTS.md.

For Claude Code -> Codex moves, the split that has worked best is:

  1. nearest AGENTS.md / CLAUDE.md files that map directly
  2. Claude-specific harness surfaces that need advisory notes instead of blind copies: hooks, MCP env refs, skills, subagents
  3. generated/session artifacts that should stay out of Codex instructions

No-data checklist JSON here if useful for comparing that shape: https://bringyour.ai/codex-import-checklist.json

anrooo · 2 months ago

This is keeping me from switching from Claude Code, it's really tough to have pretty well-configured AGENTS.md files everywhere only to have Codex ignore them entirely.

leonardo-panseri · 1 month ago

Will be staying on Claude Code until this is fixed. The documentation clearly states that you should open the Codex CLI in the subdirectory if you want AGENTS.md and skills to load, but this is not reasonable for most projects. The agent should be able to work on multiple packages/microservices in the same repo without me having to open one different codex tab for each one and manually dividing work between them.

evelant · 1 month ago

I didn't even realize codex didn't do this, I read the agents.md standard and assumed that it did! The hard requirement of tying things to a particular cwd makes a lot of things difficult with codex that should be easy.

jswny · 29 days ago

This is a pretty critical feature, how can you possibly support progressive disclosure in a large code base without this?

I didn't even realize this wasn't supported

rthug9 · 24 days ago

Commenting to echo the sentiment of this thread; I can't believe this isn't standard. Instead of providing even the most basic features, OpenAI is focused on Titan V1 chip design and wonders why Anthropic is taking so much market share. What a waste of resources.

rkhamilton · 19 days ago

I agree with the comment that this is a major problem, and it is preventing me from switching from Claude Code to Codex.

In my projects, I maintain subsystem-specific instruction files (currently CLAUDE.md) alongside the implementation. For example, Rendering/AGENTS.md documents rendering invariants, Persistence/AGENTS.md documents transaction rules, and Networking/AGENTS.md documents API conventions. These files contain assumptions and constraints that are essential for making correct changes, but they are only applicable when working within that subsystem.

The benefit of dynamic loading appears when working on features or bugs that span multiple subsystems. I always start an agent from the repository root and expect it to traverse the repository as it investigates the codebase. A task may move from UI code into networking, then persistence, then rendering. As the agent enters each subsystem, I want it to automatically pick up the local architectural guidance for that part of the codebase. Requiring everything to be duplicated in a single root AGENTS.md is not a practical solution (pollutes context, doesn't scale). Requiring the root AGENTS.md to explicitly tell the model when to read other AGENTS.md files is also fragile: it creates another file that must be kept in sync as the repository evolves, and I don't have confidence that the agent will consistently remember to follow those instructions.

Dynamic loading lets each subsystem own its own documentation, keeps instructions localized and maintainable, and ensures the agent has the right context at the point where it is reasoning about that code. This is especially important for larger repositories and cross-cutting work, where the relevant architectural constraints naturally change as the agent traverses different parts of the codebase.