AGENTS.md for Codex CLI: what the file is and how to write it

AGENTS.md in Codex CLI is a file the agent reads before it starts working, so it knows your project's rules: how to install dependencies, how to run tests, which code conventions apply. It isn't a config file with models and tools. It's plain Markdown, essentially a README for the agent. Below is how Codex discovers these files, what to put in them, and how to connect Codex to Zukko. Everything was checked against the official Codex AGENTS.md guide and the agents.md website.

What AGENTS.md is

AGENTS.md is an open format for instructions to coding agents. It has no required structure and no special fields: Codex concatenates the files it finds and adds them to its instructions at the start of a session. Lines like "Model: gpt-5.6-sol" or "Tools: file_write" in AGENTS.md configure nothing. The model and provider are set in config.toml; tools and permissions come from Codex flags and settings.

Other agents understand the same file. The agents.md website lists support from, for example, Cursor, Aider, Zed, Gemini CLI, Kilo Code and RooCode. One AGENTS.md in the repo serves the whole team, whatever agent each person uses.

How Codex discovers AGENTS.md

The instruction chain is built once at startup (in the interactive UI, at the start of each session):

1. Global scope. In the Codex home directory (~/.codex, unless CODEX_HOME is set), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file counts.
2. Project scope. Starting at the project root (usually the git root), Codex walks down to the current directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames, taking at most one file per directory.
3. Merge. Files are joined from the root down, separated by blank lines. Instructions closer to your working directory come later, so they override broader ones.

Empty files are skipped. Codex stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default). You can raise the limit in ~/.codex/config.toml:

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

AGENTS.override.md is handy for temporary changes: put it next to the regular file and it takes effect; delete it and the shared rules come back.

What to put in AGENTS.md

Write down whatever the agent would otherwise have to guess or discover by trial runs:

• install, build, lint and test commands, exactly as you run them;
• where things live, if the layout isn't obvious;
• conventions the linter doesn't catch: naming, layering, where new modules go;
• PR and commit rules;
• prohibitions: don't touch generated files, don't add dependencies without asking.

A sample root file:

## Setup
- Install deps: `pnpm install`
- Run tests: `pnpm test`
- Lint and typecheck: `pnpm lint && pnpm typecheck`

## Code style
- TypeScript strict mode, no `any` in new code
- API handlers live in `src/api/`, business logic in `src/services/`
- Never edit files in `src/generated/`, regenerate them with `pnpm codegen`

## Before you finish
- Run `pnpm lint` and `pnpm test`; fix failures before proposing a commit
- Ask before adding a new production dependency

For one part of a monorepo, put a separate file next to the code, for example services/payments/AGENTS.md with make test-payments. When Codex runs from services/payments, it picks up both the root file and this one.

What to avoid:

• generic advice like "write clean code": the agent already tries, and it costs tokens;
• copies of code or entire style guides; point to a file or the linter instead;
• outdated commands: a wrong test command is worse than none.

Creating and checking the file

In interactive Codex, /init creates an AGENTS.md scaffold in the current directory for you to edit. To check that the instructions were picked up:

codex --ask-for-approval never "Summarize the current instructions."

Codex should repeat the items from your global and project files. If something is missing, check that the file isn't empty, look for an AGENTS.override.md higher up the tree, and check which CODEX_HOME is set. There is no cache: the chain is rebuilt on every run.

Connecting Codex to Zukko

The provider and model go in ~/.codex/config.toml:

model = "gpt-5.6-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "Zukko"
base_url = "https://api.zukko.pro/v1"
wire_api = "responses"
requires_openai_auth = true

The Zukko key is stored in ~/.codex/auth.json as OPENAI_API_KEY. The simplest way to write it there is the API-key login:

export OPENAI_API_KEY="fetch_your_key"
printenv OPENAI_API_KEY | codex login --with-api-key

~/.codex/auth.json holds the key in plain text, so treat it like a password. Create the key in your Zukko dashboard↗; the step-by-step setup is in the Zukko Codex docs↗. For the current model list, call GET https://api.zukko.pro/v1/models or open the Models page in your dashboard. Switch models mid-session with /model.

AGENTS.md size and token spend

AGENTS.md instructions are part of the context the agent sends with every model request in a session, so the file's size multiplies by the number of requests. Example: AGENTS.md takes 2,000 tokens and the session makes 200 requests. That's 2,000 × 200 = 400,000 input tokens, which on gpt-5.6-sol ($0.3 per 1M) costs 0.4 × $0.3 = $0.12. A caveat about caching: vendors charge about 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the normal input price. For repeated blocks like this, the real gap versus official pricing is smaller than a straight price comparison suggests.

You can measure the file in tokens with the count_tokens↗ endpoint:

jq -n --rawfile t AGENTS.md '{model: "claude-sonnet-5", messages: [{role: "user", content: $t}]}' |
curl -s https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_your_key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @-

The response contains input_tokens. GPT models use a different tokenizer, so the number will differ a little, but it's good enough to gauge size.

FAQ

Can AGENTS.md specify which model to use?

No. AGENTS.md is instruction text only. Set the model with the model key in config.toml, or with /model during a session.

How is AGENTS.md different from a README?

A README is for people: what the project is, how to get started. AGENTS.md is for the agent: exact commands, conventions and prohibitions that would clutter a README.

I already have a rules file with a different name. Should I rename it?

Not necessarily. Add its name to project_doc_fallback_filenames in config.toml, and Codex will read it whenever a directory has no AGENTS.md.

Should I commit AGENTS.md?

Yes, the project file belongs in the repository. Keep personal preferences in ~/.codex/AGENTS.md.