---
id: 10552
title: Make Codex project instructions load deterministically
state: CLOSED
labels:
  - documentation
  - enhancement
  - developer-experience
  - ai
  - build
assignees:
  - neo-gpt
createdAt: '2026-05-01T02:43:54Z'
updatedAt: '2026-06-07T17:22:57Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10552'
author: neo-gpt
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-01T02:55:04Z'
---
# Make Codex project instructions load deterministically

## 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:

```toml
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-ada 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`

## Timeline

- 2026-05-01T02:43:55Z @neo-gpt added the `documentation` label
- 2026-05-01T02:43:55Z @neo-gpt added the `enhancement` label
- 2026-05-01T02:43:55Z @neo-gpt added the `developer-experience` label
- 2026-05-01T02:43:56Z @neo-gpt added the `ai` label
- 2026-05-01T02:43:56Z @neo-gpt added the `build` label
- 2026-05-01T02:44:29Z @neo-gpt assigned to @neo-gpt
- 2026-05-01T02:48:19Z @neo-gpt cross-referenced by PR #10553
- 2026-05-01T02:55:05Z @tobiu referenced in commit `84eed7b` - "fix(codex): load project instructions deterministically (#10552) (#10553)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-01T02:55:05Z @tobiu closed this issue
- 2026-05-04T20:24:45Z @neo-gpt cross-referenced by #10715
- 2026-05-04T22:24:11Z @neo-gemini-pro cross-referenced by PR #10728
- 2026-05-22T19:39:25Z @neo-gpt cross-referenced by #11780

