LearnNewsExamplesServices
Frontmatter
id10552
titleMake Codex project instructions load deterministically
stateClosed
labels
documentationenhancementdeveloper-experienceaibuild
assigneesneo-gpt
createdAtMay 1, 2026, 4:43 AM
updatedAtMay 1, 2026, 4:55 AM
githubUrlhttps://github.com/neomjs/neo/issues/10552
authorneo-gpt
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 1, 2026, 4:55 AM

Make Codex project instructions load deterministically

Closeddocumentationenhancementdeveloper-experienceaibuild
neo-gpt
neo-gpt commented on May 1, 2026, 4:43 AM

Context

During Codex harness hygiene analysis, @tobiu challenged whether Codex can load multiple Markdown files into turn-visible memory/instructions. A web/source check against current OpenAI Codex documentation and local codex debug prompt-input showed that the current .codex/CODEX.md fallback wiring from #10485 does not behave as intended when the repository root already contains AGENTS.md.

This ticket is a corrective follow-up to #10485, not a replacement for it.

The Problem

The current Codex project config contains:

project_doc_fallback_filenames = [".codex/CODEX.md"]

However, Codex project-doc discovery includes at most one instruction file per directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames. Because the repo root already has AGENTS.md, the .codex/CODEX.md fallback is not selected for the repo-root directory.

A second problem compounds this: root AGENTS.md is larger than Codex's default project-doc budget.

Empirical anchors from this session:

  • AGENTS.md is 55,424 bytes.
  • .codex/CODEX.md is 451 bytes.
  • Default codex debug prompt-input truncates late AGENTS.md sections.
  • codex debug prompt-input -c 'project_doc_max_bytes=120000' makes late AGENTS.md sections visible.
  • Even with the larger budget, .codex/CODEX.md still does not load, matching the one-file-per-directory rule.
  • OpenAI Codex docs identify project_doc_max_bytes as the knob for the byte budget and describe the one-file-per-directory discovery order.

The Architectural Reality

This work belongs to the Codex harness bootstrap/config surface, not the Neo framework runtime.

Relevant repository files:

  • .codex/config.template.toml — committed Codex Desktop config template for future sessions.
  • .codex/config.toml — local ignored Codex config used by this workspace.
  • .codex/CODEX.md — tiny Codex identity/auth caveat note introduced by #10485.
  • AGENTS.md — canonical per-turn operational mandates, already root-discovered by Codex.

Codex memories are not the right substrate for hard invariants. Official Codex docs frame memories as background-generated cross-thread recall. Required swarm invariants must remain in deterministic project instructions and Neo Memory Core.

The Fix

Make the Codex instruction loading path explicit and deterministic:

  1. Update the committed Codex config template so future Codex sessions raise project_doc_max_bytes high enough to load the current root AGENTS.md fully.
  2. Update the local ignored Codex config in the same way for this workspace.
  3. Remove or annotate the misleading .codex/CODEX.md fallback assumption so future agents do not believe it is automatically loaded while root AGENTS.md exists.
  4. Preserve the tiny Codex identity/auth note in a place or shape that future Codex agents can actually see, without duplicating the canonical operational mandates.
  5. Verify with codex debug prompt-input that late AGENTS.md content is visible under the corrected config.

Acceptance Criteria

  • .codex/config.template.toml sets a documented project_doc_max_bytes value large enough for the current AGENTS.md plus near-term growth.
  • Local .codex/config.toml is updated consistently for this workspace.
  • The repo no longer implies .codex/CODEX.md is automatically loaded via fallback when root AGENTS.md exists.
  • The Codex identity/auth caveat remains available to future Codex agents through a deterministic path.
  • codex debug prompt-input evidence is captured in the PR body showing late AGENTS.md sections load after the change.
  • The PR explicitly asks @neo-opus-4-7 for review, per @tobiu's coordination request.

Out of Scope

  • Rewriting the entire Codex harness bootstrap architecture.
  • Replacing Neo Memory Core with Codex memories.
  • Adding broad new swarm invariants to AGENTS.md unrelated to Codex instruction loading.
  • Changing Antigravity or Claude harness prompts.
  • Opening a new ideation discussion; this is an actionable correction with empirical evidence.

Avoided Traps / Gold Standards Rejected

  • Relying on Codex memories for hard rules. Rejected. Memories are useful recall, not deterministic instruction loading.
  • Adding more fallback files at repo root. Rejected. Codex selects at most one project-doc file per directory; root AGENTS.md wins before fallbacks.
  • Duplicating AGENTS.md into .codex/CODEX.md. Rejected. This creates drift and wastes prompt budget.
  • Using AGENTS.override.md at repo root. Rejected unless deliberately replacing root AGENTS.md; it would shadow rather than compose with AGENTS.md.

Related

  • Follow-up to #10485.
  • Related ideation context: #10546 harness hygiene / direct-to-dev prevention thread.
  • Official Codex docs consulted during diagnosis: Custom instructions with AGENTS.md, Configuration Reference, and Memories.

Origin Session ID: af8b6e6f-0b10-43f0-ace4-aa8e8f736428

Handoff Retrieval Hints: Codex project_doc_fallback_filenames .codex/CODEX.md project_doc_max_bytes AGENTS.md truncation one file per directory deterministic project instructions

tobiu referenced in commit 84eed7b - "fix(codex): load project instructions deterministically (#10552) (#10553) on May 1, 2026, 4:55 AM
tobiu closed this issue on May 1, 2026, 4:55 AM