show-me · issue 3984

Codex AGENTS.md is directory-scoped context, not Claude-style file-touch rules

Codex CLI and Claude Code both try to make repository instructions harder to miss. They choose different trigger seams: Codex starts from the active working directory; Claude rules, as described in the issue, start from the path of each touched file.

1.One-sentence answer

Codex CLI deterministically loads the AGENTS.md chain from project root to the active CWD, then relies on the model prompt to check deeper or outside-CWD AGENTS.md files; Claude Code rules are glob-based and fire on matching file operations.

Codex Directory boundary

AGENTS.md can appear in any directory. The scoped unit is that directory's subtree, with deeper files taking precedence by instruction.

Claude File path boundary

The issue describes .claude/rules/*.md files whose paths: globs are injected when matching files are read or edited.

2.The two trigger seams

Codex AGENTS.md versus Claude rules trigger diagram Codex scans from project root to current working directory. Claude rules match file paths during tool operations. Codex: active directory → instruction chain repo rootAGENTS.md subdirAGENTS.md active CWDturn env cwd model-visible AGENTS.md instructionsroot → CWD, byte-limited, source-tracked deeper paths:model is toldto check Claude rules in the issue: touched file → glob rules Read/Edit toolsrc/api/foo.ts paths: glob matchsrc/api/**/*.ts matching rule injectedoperation-scoped context
Fig 1 · Codex binds instructions to the active directory chain; Claude-style rules bind them to file-operation path matches.

Codex algorithm in plain English

  1. For each selected turn environment, Codex asks the environment filesystem for its CWD and calls read_agents_md. agents_md.rs:45-74
  2. It finds the project root by walking upward until a configured marker is found; default markers include .git. It does not walk past that root. agents_md.rs:1-16 147-199
  3. It searches directories from root to CWD and picks one candidate instruction file per directory. AGENTS.override.md wins over AGENTS.md, then configured fallbacks follow. agents_md.rs:201-235
  4. It reads non-empty files into ordered, model-visible instruction entries, truncating to project_doc_max_bytes. agents_md.rs:83-145
  5. The base prompt also tells the model that AGENTS.md files can appear anywhere, apply to their containing subtree, and must be checked when working below or outside the CWD. default.md:17-27

3.Comparison table

DimensionCodex CLI AGENTS.mdClaude Code rules, as described in issue #3984
Authoring shapePlain AGENTS.md in any directory; current Codex also has AGENTS.override.md and configured fallback filenames.Markdown files under .claude/rules/ or ~/.claude/rules/, with optional YAML paths:.
Scope modelDirectory subtree rooted where the file lives; deeper AGENTS.md wins on conflicts by prompt contract.Glob match against touched file paths; rules without paths act like always-on context.
Automatic triggerDeterministic for the active root→CWD chain that Codex discovers and injects.Deterministic for matching Read/Edit file operations, per the issue body.
Model-dependent partWhen working in a subdirectory below CWD or outside CWD, the prompt tells the model to check for applicable AGENTS.md; that is instruction-following, not a file-operation hook.No model decision for path-scoped rules once the tool path matches the glob.
GranularityGood for nested directory ownership boundaries; less direct for “all tests everywhere” unless files share directories or the model checks broader docs.Good for cross-cutting patterns like **/*.test.ts that span many directories.
Token behaviorOnly the root→CWD chain is injected automatically, and Codex enforces a byte budget.Path-scoped rules stay out of baseline context until a matching file operation; overly broad globs become effectively always-on in file-heavy work.
Source visibilityCodex tracks and exposes instruction source paths through instruction_sources.The issue does not describe a comparable source reporting surface.

4.Gotchas that matter for SDK design

Codex is not a drop-in precedent for Claude rules. It proves directory-scoped instruction discovery is useful, but it does not implement a glob-based “inject when this file is read/edited/created” trigger.
  • Dynamic CWD refresh is nuanced. A Codex suite test has a TODO to diff user_instructions when AGENTS.md changes after CWD changes; the current snapshot asserts no refreshed AGENTS content in that case. model_visible_layout.rs:203-206 310-325
  • Remote/deferred environments still get deterministic project-doc loading once available. The remote environment test observes AGENTS content in later requests and records the loaded source. remote_env.rs:722-728
  • The SDK design implication is a hybrid. Codex-style directory memory maps naturally to repository context and plugin/package ownership; Claude-style path rules require a tool-use seam that evaluates paths on Read/Edit/Write and injects matched content deterministically.

5.Source map and validation

ClaimEvidence
Codex scans from project root to CWD and stops at project root.agents_md.rs:1-16
Codex loads project instructions for each turn environment.agents_md.rs:45-74
Codex candidate names include override, default, and fallbacks.agents_md.rs:222-235
Codex prompt assigns subtree scope, nested precedence, and self-checking below/outside CWD.default.md:17-27
This page follows SmolPaws show-me conventions: self-contained HTML, big-picture first, code-grounded claims.show-me/SKILL.md:1-65 SmolPaws AGENTS.md:55-59
Claude rules behavior summarized here is the issue's stated behavior, not independently reverse-engineered Claude Code source.OpenHands/software-agent-sdk#3984
Validation note

This is a source-inspection report. I cloned openai/codex at 98d28aab54ed86714901b6619400598598876dd0 and smolpaws/smolpaws at b15dc60f72b9b926cd9931efed1e081190969679. I did not run Codex's Rust test suite because the task was investigative documentation, not a code change.

Created by an AI agent (OpenHands) on behalf of the issue request.