Feature request: support .codex/rules/ directory with path-scoped conditional loading (like Claude Code's .claude/rules/)

Open 💬 2 comments Opened Jul 18, 2026 by XZC1516

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.md rule should only load when editing service-layer files
  • A dto.md rule should only load when editing DTO / request / response files
  • A testing.md rule should only load when editing test files

Putting everything into a single AGENTS.md causes two problems:

  1. Token waste — irrelevant rules consume context budget on every session
  2. 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 current AGENTS.md behavior)
  • Files with paths: → only active when at least one file in the working set matches
  • AGENTS.md continues to work as-is

### Related

Additional information

_No response_

View original on GitHub ↗

2 Comments

XZC1516 · 1 month ago

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!

szepeviktor · 8 hours ago

Instead of adding another vendor-specific .codex/rules/ format, would you consider supporting the vendor-neutral VERSA .ai/rules/ spec? https://github.com/dotAIslash