[codex] Add AGENTS.local overlays, @-reference expansion, and source file attribution / provenance like Claude Code

What variant of Codex are you using?

Desktop App / CLI

What feature would you like to see?

Summary

Add AGENTS.local.md as an additive instruction overlay and expand @ references from project AGENTS files.

AGENTS.override.md can keep its existing replacement semantics. The new local file would be appended after the effective base instructions, so users can add machine- or workspace-specific guidance without shadowing checked-in project instructions.

Context

Codex currently discovers project instructions by walking from the project root to the selected cwd, choosing one effective instruction file per directory, then rendering the concatenated result into the model-visible AGENTS.md instructions block. That supports repo-shipped instructions and hard local replacement via AGENTS.override.md, but it does not provide an additive local overlay.

It also flattens discovered instruction text without preserving per-file provenance, and project instructions cannot import shared fragments from nearby files.

For motivation, Claude Code publicly documents analogous memory-file ergonomics for CLAUDE.md, local memory files, and @ imports: https://code.claude.com/docs/en/memory#claude-md-files. This feature would be to adapt those broad usability ideas to Codex's existing AGENTS conventions rather than changing the current override behavior.

---

Additional information

I have a branch for this here but don't have permission to open a PR.

Here's essentially how it works:

Behavior

Within each searched directory, Codex now loads:

1. The effective base instruction file: AGENTS.override.md, otherwise AGENTS.md, otherwise configured fallbacks.
2. AGENTS.local.md, when present.

The same overlay rule applies to global instructions under Codex home: the selected global base is loaded first, then AGENTS.local.md is appended when present.

Project instruction files can now reference nearby files with @path syntax. References resolve relative to the including file, expand depth-first, and are deduplicated with cycle protection. Expanded fragments are rendered as their own source-labeled instruction entries.

Representative example:

repo/
  AGENTS.md
  AGENTS.local.md
  docs/testing.md

If AGENTS.md contains @docs/testing.md, the model-visible project section is shaped like:

Instructions from `/repo/AGENTS.md`

<contents of AGENTS.md>

Referenced instructions from `/repo/docs/testing.md`

<contents of docs/testing.md>

Local additions from `/repo/AGENTS.local.md`

<contents of AGENTS.local.md>

It also labels global/Codex-home instruction sources in the model-visible AGENTS block, preserving provenance for out-of-cwd global AGENTS.md relative references and covering #29535.

Nuances

AGENTS.override.md remains a replacement for the base file in the same directory. AGENTS.local.md is additive, including when an override file is the selected base.

Reference expansion is intentionally conservative. Referenced project files are canonicalized through the executor filesystem and only included when their canonical target remains inside the canonical project root. This avoids symlink or alias escapes. It also means Codex does not currently implement an interactive approval path for imports outside the project root.

Codex preserves logical AGENTS discovery for cwd/project-root walking, including symlinked cwd layers. Canonicalization is applied to referenced files for containment and dedupe, not to collapse the logical discovery walk itself.

References skip Markdown code spans, fenced code blocks, and HTML comments. Missing or non-file references are ignored; unexpected filesystem errors still surface through the existing loading path.

Approach

The implementation separates replacement and additive instruction sources, carries source-kind provenance through rendering, and labels each project fragment by source path. Project reference expansion is handled during AGENTS loading with bounded depth, bounded file count, canonical dedupe, and existing byte-budget enforcement. Coverage was added at the core loader, Codex-home loader, and exec request layers.