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

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 ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗