›_ Codex Issues
Codex Issues / #22454

project_doc_fallback_filenames=["CLAUDE.md"] does not inject project instructions, while AGENTS.md works

Resolved 💬 3 comments Opened May 13, 2026 by austingg Closed May 19, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What version of Codex CLI is running?

0.130.0

What subscription do you have?

api

Which model were you using?

_No response_

What platform is your computer?

RockyLinux 9.5

What terminal emulator and version are you using (if applicable)?

_No response_

What issue are you seeing?

Summary

project_doc_fallback_filenames = ["CLAUDE.md"] appears to be recognized by config, but in practice CLAUDE.md is not injected as project
instructions.

In the same environment, AGENTS.md works correctly.

This looks like a bug in project-doc discovery / prompt construction rather than a provider-side issue.

## Codex Version

  • codex-cli 0.130.0

## Config

My ~/.codex/config.toml contains:

```toml
[project]
project_doc_fallback_filenames = ["CLAUDE.md"]

## What I Expected

If a repository does not contain AGENTS.md but does contain CLAUDE.md, then Codex should inject CLAUDE.md as the project instruction document.

## What Actually Happened

  • CLAUDE.md was not injected into the model-visible prompt input.
  • The session only contained the normal base/developer instructions.
  • I had to manually open/read CLAUDE.md from the workspace.
  • In contrast, when I created a test directory containing only AGENTS.md, Codex injected it correctly.

## Why this seems CLI-side, not provider-side

I verified this with:

codex debug prompt-input

This command shows the model-visible input list before the request is sent.

So if CLAUDE.md is missing there, the problem seems to happen in local prompt construction / project-doc discovery, before provider transport.

What steps can reproduce the bug?

Reproduction

### Case 1: AGENTS.md works

Create a temp directory with only AGENTS.md:

mkdir -p /tmp/codex-doc-test-agents
cp CLAUDE.md /tmp/codex-doc-test-agents/AGENTS.md
cd /tmp/codex-doc-test-agents
codex debug prompt-input

Actual result:

The output includes a block like:

# AGENTS.md instructions for /tmp/codex-doc-test-agents

So AGENTS.md is injected correctly.

### Case 2: CLAUDE.md fallback does not work

Create a temp directory with only CLAUDE.md:

mkdir -p /tmp/codex-doc-test-claude
cp CLAUDE.md /tmp/codex-doc-test-claude/CLAUDE.md
cd /tmp/codex-doc-test-claude
codex debug prompt-input

Actual result:

  • No project instruction block is injected
  • No CLAUDE.md content appears in prompt input

Expected result:

  • CLAUDE.md should be injected because project_doc_fallback_filenames = ["CLAUDE.md"] is configured

## Additional Notes

This does not seem to be caused by /new vs restarting the TUI.

I tested with a fresh codex debug prompt-input process, and the behavior was the same:

  • AGENTS.md loads
  • CLAUDE.md fallback does not load

So this seems reproducible even in a fresh process.

What is the expected behavior?

_No response_

Additional information

_No response_

View original on GitHub ↗

3 Comments

unitedideas · 3 months ago

This is the same failure class that shows up during Claude Code -> Codex imports: the file can exist in the target repo, but the migrated harness is still broken if the new runtime never injects it.

A useful regression shape here might be:

  1. Fixture repo has only CLAUDE.md, with a deliberately visible instruction marker.
  2. Config sets project_doc_fallback_filenames = ["CLAUDE.md"].
  3. The assembled prompt/session context is asserted to contain that marker before the model turn.
  4. The same fixture then adds AGENTS.md and verifies precedence is deterministic, not accidental.

That keeps the test focused on discovery + injection rather than just config parsing. I have been using the same distinction in Codex import audits because AGENTS.md/CLAUDE.md migration can pass a filesystem check while still failing at prompt assembly time.

Related checklist, if useful for migration test cases: https://bringyour.ai/codex-import-checklist

etraut-openai contributor · 3 months ago

I think the root cause is config placement, not project-doc discovery.

project_doc_fallback_filenames is currently a top-level config key, not a [project] key:

project_doc_fallback_filenames = ["CLAUDE.md"]
austingg · 3 months ago

@etraut-openai thanks. when i set it top-level config, it works.