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

Open 💬 0 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 ↗