Instructree

Codex troubleshooting guide

Debug Codex AGENTS.md before your next session.

When an instruction looks present on disk but absent in Codex, guessing from the model's response is unreliable. Inspect the deterministic pre-session inputs first: the selected project root, file precedence, shared byte budget, global user instructions, and skill configuration.

npx --yes github:kotobuki09/instructree#v0.22.0 doctor .

Local static analysis · zero runtime dependencies · no model call · does not upload repository content

The fast answer

Start with the root boundary, not the file you expected.

Codex chooses the nearest project-root marker while walking upward from the working directory. By default that marker is .git; user configuration can replace or extend the marker list. Even an empty nested .git directory can therefore select a nearer root. Discovery then runs only from that selected root down to the working directory. It does not continue into an outer repository, so a nested project-root marker can change the entire instruction chain.

A common surprise

An empty nested .git directory is still a filesystem marker. A submodule or worktree can also introduce a nearer marker. In all three cases, a parent AGENTS.md may look relevant to a human while remaining outside Codex's selected project chain.

Instructree reports that distinction without silently adding the parent file:

root boundary: 1 parent instruction ignored above selected project root
- <parent>/AGENTS.md · ignored above selected project root
- outer marker: .git at <parent>

The redacted <parent> label makes the output suitable for an issue report without exposing a home directory or checkout path.

Diagnostic checklist

Five reasons Codex instructions appear to be missing.

  1. The nearest project-root marker is not the root you expected

    Check the reported marker and working-directory path first. If a nearer marker exists, parent project instructions are out of scope. The doctor reports an outer marker only when it finds an actual nested project boundary, keeping ordinary standalone repositories quiet.

  2. An override or fallback won in the same directory

    Codex checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames. It selects the first regular candidate. An empty project candidate still blocks lower-priority names in that directory, so inspect the selected filename instead of only checking whether AGENTS.md exists.

  3. The shared byte budget was exhausted

    The root-to-current-directory instruction chain uses one shared byte budget controlled by project_doc_max_bytes. A large broad file can leave less space for a more specific file. The doctor reports included bytes, truncation, and whether the combined budget was exhausted.

  4. Global user instructions and project instructions were conflated

    Global user instructions live under ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md. Their selection rule is separate from the repository chain. An empty global override is skipped, while an empty project candidate remains selected. The doctor presents these surfaces separately.

  5. A discovered skill is disabled by user config

    A skill can exist on disk but be disabled by user config. The report applies the supported subset of ~/.codex/config.toml, including later-rule precedence, and labels candidates disabled by user config, unmatched selectors, malformed metadata, duplicate names, and approximate list pressure.

Symptom map

Match the symptom to the evidence.

Symptom Inspect Useful signal
Parent rules disappear in a submodule Selected and outer project markers repository.boundary
The wrong file wins in one directory Override, standard, fallback precedence instructions.project.files
Rules near the end are absent Included bytes and combined limit budgetExhausted
Personal defaults seem absent User instruction selection instructions.user
A skill exists but does not activate User skill-config rules and metadata disabledByUserConfigCount
Share-safe evidence

Capture the configuration result without dumping a session.

For a deterministic report suitable for tooling or a minimal bug reproduction, add --json:

npx --yes github:kotobuki09/instructree#v0.22.0 doctor . --json

Both text and JSON replace the repository and home locations with logical labels. The command reads only the supported user-config subset and fails closed when relevant TOML syntax is outside that subset.

Important boundary

This is a static pre-session preview. It does not inspect a running or resumed Codex session, managed configuration, profiles, session flags, project trust, remote environments, plugins, or model adherence. A clean report is not proof that a model followed every loaded instruction.

Primary evidence

The checks follow documented and source-pinned behavior.

Next step

Run the report from the directory where Codex will start.

The working directory is part of the discovery result. Run the doctor there, inspect any attention signals, and only then change an instruction file or marker.

Get Instructree Read the Codex setup