Instrument 07 / Codex configuration

Generate the Codex project-doc config your repository needs.

Choose fallback instruction files, set the project guidance byte limit, and copy one inspectable config.toml snippet.

Build a valid snippet

Configure fallback docs without overriding AGENTS.md.

Everything runs in this browser. The generator accepts filename-safe values, removes duplicates, and keeps the documented 32 KiB default visible.

Fallback instruction files

Select files Codex should try when AGENTS.md is missing at a directory level.

TEAM_GUIDE.mdTeam conventions CLAUDE.mdExisting agent guidance CONTRIBUTING.mdContribution workflow PROJECT_GUIDE.mdProject-specific rules

Additional filenamesComma-separated filenames only. Paths and invalid characters are ignored. Project guidance limit32 KiB is the documented default. Raise it only when project instructions are being truncated.

Generated snippetREADY

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", "CLAUDE.md"]
project_doc_max_bytes = 65536

Fallback files2

Instruction limit64 KiB

AGENTS.md priorityPreserved

Data sentNone

Codex checks AGENTS.md before these ordered fallback names.

Daily evidence brief · 52,000+ readers Get the next engineering teardown →

Resolution order

AGENTS.override.md first.
It takes precedence at each directory level.

AGENTS.md next.
Fallback names are tried only when it is absent.

Root to working directory.
Closer guidance appears later and can override earlier instructions.

Current Codex behavior

What the generated Codex config.toml changes.

project_doc_fallback_filenames adds ordered filename candidates after AGENTS.override.md and AGENTS.md. It is useful when a repository already keeps durable instructions in files such as TEAM_GUIDE.md or CLAUDE.md.

project_doc_max_bytes controls how much project guidance can enter the initial instruction chain. The documented default is 32 KiB. A larger number prevents truncation but also consumes more context.

Personal scope lives in ~/.codex/config.toml. Supported project defaults can live in .codex/config.toml when the repository is trusted.

Reload required. Start a new Codex command or session after changing configuration so the instruction discovery process runs again.

Codex CLI guide

The four questions behind these two settings.

Use fallback files to reuse real repository guidance, not to create a second conflicting instruction system.

Read the full Codex CLI technical guide → Auditing an agent workflow next? →

What does project_doc_fallback_filenames do?

It gives Codex an ordered list of additional instruction filenames to try when AGENTS.md is missing at a directory level.

What does project_doc_max_bytes do?

It sets the byte limit for project guidance Codex reads into the initial instructions. The documented default is 32,768 bytes, or 32 KiB.

Does a fallback file replace AGENTS.md?

No. Codex checks AGENTS.override.md and AGENTS.md first. Fallback filenames are tried only when AGENTS.md is absent at that level.

Where should Codex config.toml go?

Personal defaults belong in ~/.codex/config.toml. Trusted projects can also use .codex/config.toml for supported project-scoped settings.