Codex AGENTS.md: the 32 KiB limit and your design rules

Codex stops adding project instructions once the AGENTS.md text it has collected reaches 32 KiB, which is 32,768 bytes. The setting is project_doc_max_bytes in ~/.codex/config.toml. OpenAI's Codex documentation gives 32 KiB as the default, and its configuration reference describes the setting as the maximum number of bytes read from AGENTS.md when Codex builds the project instructions (checked 6 Nov 2026; the developers.openai.com addresses now redirect to the ChatGPT Learn pages cited below). To allow more, add a line such as project_doc_max_bytes = 65536 to config.toml and start a new Codex session. Instructions past the limit are cut off, so a rule at the bottom of a long file may never reach the model. A shorter AGENTS.md that points to design.md, or a nested AGENTS.md in each folder it governs, usually works better than a higher limit.

This page is for a founder who put a design.md file in a project and expected the coding tool to follow it. Codex, Claude Code, and Gemini do not look for that filename. Each one reads a different instruction file. Your prices, colors, and refusals are invisible until that instruction file tells the tool to open design.md. The notes below come from each product's own documentation on 22 September 2026; the Codex details were checked again on 6 November 2026. This page does not report a run inside any of the three products. The longer Codex walkthrough stays at the existing article, DESIGN.md for Codex.

Codex looks for instructions in two places. In your Codex home folder it reads AGENTS.override.md if that file exists, and otherwise AGENTS.md. Inside the project it starts at the project root and walks down to the folder you are working in. It takes at most one instruction file from each folder and joins them into one note. Files closer to your work come last, so they can override the earlier ones. Empty files are skipped. It stops adding text when the combined note reaches 32 KiB by default. The setting is named project_doc_max_bytes, and the limit is measured in bytes, not characters. Do not paste a whole design system into AGENTS.md. Codex has no documented reason to open design.md unless AGENTS.md tells it to. The fallback list in config.toml helps only in folders that have no AGENTS.md.

Claude Code reads CLAUDE.md when a session starts. The memory guide treats that file as background the model can see, not as a lock that stops a bad edit. It suggests keeping CLAUDE.md under about 200 lines, and putting a step-by-step procedure in a skill that is loaded only when the task needs it. design.md is not on Claude's list. Import it from CLAUDE.md, or tell the session to open it. AGENTS.md is the awkward case. By default Claude reads AGENTS.md only when the project has no CLAUDE.md and no CLAUDE.local.md. That direct read needs Claude Code version 2.1.277 or later. If CLAUDE.md is already there, Claude reads CLAUDE.md and skips AGENTS.md unless you change the project-instructions setting. Some sessions, including Amazon Bedrock, cannot read AGENTS.md at all. In those sessions, import the rules from CLAUDE.md.

Gemini CLI reads GEMINI.md files through the project hierarchy. A project file can import another file, and the context.fileName setting can change the filename Gemini looks for. Check the current Gemini CLI documentation before depending on an account-specific or preview feature. Keep one source of truth and inspect the hierarchy and imported files so the same rule is not repeated in several places.

Leave the visual rules in design.md. Then add one short pointer in the file the tool already reads. For Codex, put a line in AGENTS.md that says to read design.md before changing marketing pages. The fallback list in config.toml is tried only in folders with no AGENTS.md, and the combined instructions still stop at 32 KiB by default. For Claude Code, import design.md from CLAUDE.md with the @path syntax in the memory guide, or keep the short rules in CLAUDE.md and put the long example in a skill. For Gemini CLI, import design.md from GEMINI.md or add the filename through context.fileName. These rules can change, so recheck the product page before you hand the steps to someone else.

It is a number in ~/.codex/config.toml that caps how many bytes Codex reads from AGENTS.md files when it builds the project instructions. The default is 32 KiB. Codex reads AGENTS.override.md or AGENTS.md from your Codex home folder, then one file per folder from the project root down to your working folder, and stops when the total reaches the limit. Raise the number, or split the instructions into nested AGENTS.md files, if rules near the end of AGENTS.md are being ignored.

No. Codex looks for AGENTS.override.md, AGENTS.md, and any names you list in project_doc_fallback_filenames, and the fallback names are tried only in a folder with no AGENTS.md. Add one line to AGENTS.md that tells Codex to read design.md before it changes the website. That line costs a few bytes of the 32 KiB limit, while the design rules themselves stay in design.md.

iter0 is a website builder, not a coding agent. A site built in iter0 keeps one header, footer and style across its pages, so its pages do not drift apart the way separate agent sessions can. When you want Codex to work on the site, you can connect Codex to iter0 through its MCP server, or have iter0 open a pull request in your GitHub repository and let Codex continue in the code with your AGENTS.md. You can try it free at iter0.com.