Why is Codex ignoring
my AGENTS.md?

Start with the launch directory

The initial project chain runs from the project root to the working directory. A file in a sibling directory is outside that path. The official AGENTS.md guide describes discovery order and fallback names.

northstar/
├── AGENTS.md
├── services/
│   ├── AGENTS.md
│   └── payments/       ← launch here
│       ├── AGENTS.md
│       └── AGENTS.override.md
└── apps/web/
    └── AGENTS.md       ← outside this chain

In the map, select services/payments, then compare it with apps/web. The comparison lists shared and different source files. Nested Git repositories can also change the root; use the CLI's --root when the intended boundary differs from automatic detection.

Look for AGENTS.override.md beside AGENTS.md

Only one filename is selected per directory. A local override can therefore hide the regular file beside it. It does not remove files from parent directories.

The hidden override demo shows a payments migration rule replacing a same-directory candidate. Expand the “other files” panel below the chain to inspect the omitted file.

Empty-file edge case: in the pinned project implementation, the first existing candidate is selected before its content is read. An empty override can still shadow its sibling. This detail is version-sensitive; try the empty override example and check your installed version before applying the finding.

Find the last byte that fits

The documented default project limit is 32,768 bytes. The demo deliberately lowers it to 1,024 bytes to make the boundary easy to see. This is a content-byte limit, not a token count.

Open the cutoff scenario, inspect the assembled preview, then reset the limit to 32 KiB. The missing final paragraph becomes visible. Splitting a long file into parent and child files along the same path does not automatically avoid a shared budget.

Match the map to your setup

The map does not load Codex configuration automatically. Supply your intended limit, fallback filenames and root. Global guidance is opt-in with --global. In the public demo, TEAM_GUIDE.md is an explicit fictional fallback.

Generate a report for your repository

With Node.js 20 or later, run:

npx codex-context-map . --html context-map.html

Open the HTML file in a browser. It works offline. To model a specific directory and explicit settings:

npx codex-context-map services/payments --root . \
  --max-bytes 32768 --fallback TEAM_GUIDE.md \
  --html context-map.html

The second command uses POSIX shell line continuations; on PowerShell, put it on one line. Use --check to return a failing exit code when the selected chain is cut off. Reports contain instruction text and relative paths: inspect them before sharing.