Feature request: support .codex/rules/ directory with path-scoped conditional loading (like Claude Code's .claude/rules/)
What variant of Codex are you using?
CLI
What feature would you like to see?
Support a project-level rules directory where individual rule files can declare path-scoped activation — only loaded when the agent is
editing files matching specific glob patterns.
### Problem
Today Codex loads project instructions via AGENTS.md — a flat file that applies to every session regardless of what file is being edited.
This works for project-wide conventions, but breaks down when a project has file-type-specific rules that should only apply in context.
For example:
- A
service.mdrule should only load when editing service-layer files - A
dto.mdrule should only load when editing DTO / request / response files - A
testing.mdrule should only load when editing test files
Putting everything into a single AGENTS.md causes two problems:
- Token waste — irrelevant rules consume context budget on every session
- Instruction dilution — rules buried in a long prompt are less likely to be followed
Nested AGENTS.md in subdirectories is a partial workaround, but it scopes by directory location rather than file type — a coarse
approximation that misses cross-cutting patterns.
### What others do
This is already solved by other tools in the space:
| Tool | Mechanism |
|---|---|
| Claude Code | .claude/rules/*.md with paths: frontmatter |
| Cursor | .cursor/rules/*.mdc with globs: frontmatter |
| Windsurf | .windsurf/rules/*.md with globs: frontmatter |
| GitHub Copilot | .github/instructions/*.md with applyTo: frontmatter |
There is also an active cross-tool standardization proposal for .agents/rules/:
https://github.com/agentsmd/agents.md/issues/179
### Proposed behavior
A .codex/rules/ directory (or adoption of .agents/rules/) where markdown files use optional frontmatter to control when they load:
.codex/rules/
├── conventions.md # no paths → always loaded
├── service-layer.md # paths: ["/service/*.kt"]
├── api-boundary.md # paths: ["/dto/.kt", "*/*Request.kt"]
└── testing.md # paths: ["src/test/**"]
- Files without
paths:→ always active (backward compatible with currentAGENTS.mdbehavior) - Files with
paths:→ only active when at least one file in the working set matches AGENTS.mdcontinues to work as-is
### Related
- #1624 — Reference Agent Rules Community Standard
- #10067 — Add
--agentsflag for named AGENTS.md variants - https://github.com/agentsmd/agents.md/issues/179 —
.agents/rules/cross-tool proposal
Additional information
_No response_
2 Comments
Hey OpenAI team,
Just following up on this — this feature is honestly pretty critical for us and I imagine for a lot of other teams working with AI agents.
The path-scoped rules pattern is already standard across Claude Code, Cursor, and Windsurf. It's not just a convenience thing either — it actually makes a huge difference in how well the AI follows instructions when you can keep them focused and relevant to what you're actually editing.
Quick question though: do you have any sense of when this might land? Even just knowing if it's on the roadmap for this quarter or next would be super helpful for planning.
The cross-tool standardization effort (
.agents/rules/) is also gaining traction, so it feels like the right time for Codex to jump on this.Would really appreciate any timeline you can share. Thanks!
Instead of adding another vendor-specific
.codex/rules/format, would you consider supporting the vendor-neutral VERSA.ai/rules/spec? https://github.com/dotAIslash