Skip to main content

04 - Codex AGENTS.md and config.toml: give it stable rules

AGENTS.md is advice, config.toml is a constraint: how Codex builds the instruction chain, where the byte cap falls and who wins in a conflict.

What do you think about this article?

04 - Codex AGENTS.md and config.toml: give it stable rules
OpenAI Codexfedericocalo.dev

At a Glance

AGENTS.md is advice, config.toml is a constraint: how Codex builds the instruction chain, where the byte cap falls and who wins in a conflict.

You have explained to Codex three times how to run your project's tests, and the fourth time it tried the wrong command again. The problem is not the agent's memory but where you wrote the rule: Codex has two places for stable rules, and they have different powers. AGENTS.md contains natural-language instructions (how the project is built, which conventions to follow, what not to touch) that the model reads and may follow badly; config.toml contains settings (model, sandbox, approvals, web search) that the program applies. According to the documentation read on November 13, 2026, Codex builds the chain of AGENTS.md files from the project root down to the current folder, and the files closest to where you work come later and therefore prevail; for config.toml the winner is, in order, the command line, then the project file (only if the project is trusted), then the profile, then your user file. The cost to keep in mind: every line of AGENTS.md enters the context at every session, and there is a byte cap.

Method and limits. I am not affiliated with OpenAI. I did not run Codex: I read the official pages on 2026-11-13 and wrote two small programs of my own that model the rules they describe, to see them at work on test files. Both were run twice with the same output (Python 3.14, Linux); they are not the Codex engine and where the documentation contradicts itself I say so.

The difference that avoids half of the mistakes

An instruction in AGENTS.md is advice; a value in config.toml is a constraint. If you want the agent not to write outside the workspace, do not write it in AGENTS.md: set sandbox_mode = "workspace-write" (part 3 explains why). If you want it to use pnpm and not npm, that is advice and goes in AGENTS.md. The practical rule is: what must always hold lives in the program, what helps to work well lives in the text. An example that shows it: "do not touch the db/migrations/ folder" in AGENTS.md is a plea, while a read-only rule on that folder in a permissions profile (the Permissions page, in beta, shows read and deny rules by path) would be a constraint; the first can be ignored through distraction, the second cannot.

How Codex finds AGENTS.md

The dedicated page describes a chain built only once per run (in the TUI, normally once per session started), in two scopes plus a merge.

  1. Global scope. In the Codex home folder (~/.codex, or the one indicated by CODEX_HOME) it reads AGENTS.override.md if it exists, otherwise AGENTS.md, and uses only the first non-empty file of this level.
  2. Project scope. It starts from the root (normally the Git root) and descends to the current folder; in each folder it checks AGENTS.override.md, then AGENTS.md, then the names in project_doc_fallback_filenames, including at most one file per folder. Without a project root it checks only the current folder.
  3. Merge. The files are concatenated from the root downwards, separated by blank lines; those closest to the current folder appear later and therefore prevail.

The order matters here: the global file comes before all the others, that of the deepest folder last, and prevalence is a consequence of position in the text, not of a replacement mechanism. The page's examples: ~/.codex/AGENTS.md for your personal preferences, AGENTS.md at the root for the repository's norms, services/pagamenti/AGENTS.override.md for an area with its own rules. The override takes precedence over the base file in the same folder and is the way to replace a guide without deleting it: in the documentation's example tree, the payments AGENTS.md is ignored because its override exists. After changing these files, restart Codex: the chain is rebuilt at startup.

The byte cap and the file that stays out

The page says that Codex skips empty files and stops adding files when the combined size reaches the limit project_doc_max_bytes, which is 32 KiB by default. The risk is silent: the reading order goes from the general to the specific, so the files left out are the deepest ones, that is, the most specific. To see it without launching Codex I wrote a model of that rule. The chain function starts from the root (the folder that contains .git), descends to the current folder, chooses in each one the first non-empty file among override, AGENTS.md and the fallback names, and stops adding files when the total has reached the limit. The tree is built in a temporary folder: a global file, one at the root, one for each service, and a TEAM_GUIDE.md under docs/.

The test files contain short Italian sentences, which are data of the experiment and whose content does not matter, only their size in bytes, which is why I left them unchanged; the folder names pagamenti and ricerca mean "payments" and "search". The printed words are in English: read are the files that enter the chain, excluded those left out.

"""Which instruction files would the agent read, and in what order? A model of the documented rule.

Rules taken from the AGENTS.md page of the Codex documentation (consulted on
2026-11-13): global scope (override, otherwise AGENTS.md, the first non-empty one);
project scope from the root to the current folder, one file per folder
(override, AGENTS.md, then the fallback names); files concatenated from the root down;
adding files stops when the combined size reaches the limit.
It is not Codex: it is a way to see the cap at work.
The test files contain short Italian sentences (they are data of the experiment);
the folder names pagamenti = payments and ricerca = search.
"""
import tempfile
from pathlib import Path

def find_root(cwd, markers=(".git",)):
    for folder in (cwd, *cwd.parents):
        if any((folder / m).exists() for m in markers):
            return folder
    return None

def first_non_empty(folder, names):
    for name in names:
        f = folder / name
        if f.is_file() and f.stat().st_size > 0:
            return f
    return None

def chain(codex_home, cwd, fallback=(), limit=32 * 1024):
    candidates = []
    global_file = first_non_empty(codex_home, ("AGENTS.override.md", "AGENTS.md"))
    if global_file:
        candidates.append(global_file)
    root = find_root(cwd)
    path = [cwd]
    if root is not None:
        descend = [cwd, *[p for p in cwd.parents if p.is_relative_to(root)]]
        path = list(reversed(descend))
    for folder in path:
        f = first_non_empty(folder, ("AGENTS.override.md", "AGENTS.md", *fallback))
        if f:
            candidates.append(f)
    included, total = [], 0
    for f in candidates:
        if total >= limit:
            break
        included.append(f)
        total += f.stat().st_size
    return included, candidates[len(included):], total

def prepare(base):
    home, repo = base / "codex_home", base / "repo"
    files = {
        home / "AGENTS.md": "Preferisco pnpm.\n",
        repo / "AGENTS.md": "Esegui pnpm lint prima di ogni PR.\n",
        repo / "docs/TEAM_GUIDE.md": "Guida della documentazione (nome di riserva).\n",
        repo / "services/pagamenti/AGENTS.md": "Test: pnpm test.\n",
        repo / "services/pagamenti/AGENTS.override.md": "Test: make test-pagamenti.\n",
        repo / "services/ricerca/AGENTS.md": "Test: pnpm --filter ricerca test.\n",
    }
    (repo / ".git").mkdir(parents=True)
    for path, text in files.items():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(text)
    return home, repo

def show(title, base, result):
    included, excluded, total = result
    rel = lambda f: str(f.relative_to(base))
    print(title)
    print("  read    :", " > ".join(rel(f) for f in included))
    print("  excluded:", ", ".join(rel(f) for f in excluded) or "none", f"({total} bytes read)")

if __name__ == "__main__":
    with tempfile.TemporaryDirectory() as t:
        base = Path(t)
        home, repo = prepare(base)
        show("from services/pagamenti", base, chain(home, repo / "services/pagamenti"))
        show("from services/ricerca", base, chain(home, repo / "services/ricerca"))
        show("from docs, without fallback names", base, chain(home, repo / "docs"))
        show("from docs, with TEAM_GUIDE.md among the fallback names", base,
             chain(home, repo / "docs", fallback=("TEAM_GUIDE.md",)))
        show("from services/pagamenti, limit 40 bytes", base,
             chain(home, repo / "services/pagamenti", limit=40))

# Command: python3 -I catena_agents.py
# Output:
# from services/pagamenti
#   read    : codex_home/AGENTS.md > repo/AGENTS.md > repo/services/pagamenti/AGENTS.override.md
#   excluded: none (79 bytes read)
# from services/ricerca
#   read    : codex_home/AGENTS.md > repo/AGENTS.md > repo/services/ricerca/AGENTS.md
#   excluded: none (86 bytes read)
# from docs, without fallback names
#   read    : codex_home/AGENTS.md > repo/AGENTS.md
#   excluded: none (52 bytes read)
# from docs, with TEAM_GUIDE.md among the fallback names
#   read    : codex_home/AGENTS.md > repo/AGENTS.md > repo/docs/TEAM_GUIDE.md
#   excluded: none (98 bytes read)
# from services/pagamenti, limit 40 bytes
#   read    : codex_home/AGENTS.md > repo/AGENTS.md
#   excluded: repo/services/pagamenti/AGENTS.override.md (52 bytes read)

Three things to read in the output. From the payments folder the chain is global, root, payments override: the AGENTS.md next to the override is not read, as in the documentation's example. From docs, the name TEAM_GUIDE.md enters the chain only if it is listed among the fallback names; without it, the folder contributes nothing. With a limit of 40 bytes (deliberately tiny) the first two files exceed the cap, and the payments file, the most specific, is not read. An honest clarification about the source: the AGENTS.md page speaks of combined size, while the reference page describes project_doc_max_bytes as the bytes read from AGENTS.md and the advanced configuration page as how much to read from each file. The model follows the first reading; to know how your version behaves, check which files appear as loaded with the verification method of the page (see below).

The two ways out, if you reach the cap, are raising the limit or, better, splitting the rules into nested files, each short and tied to its area. Even without reaching the cap, a huge file has a cost: every word is context that the agent rereads at every session and that competes with the code of the task. To verify what Codex has loaded, the documentation proposes starting from a nested folder with codex --cd services/pagamenti --ask-for-approval never "List the instruction sources you loaded.", or turning on the text log with codex -c log_dir=./.codex-log and reading ./.codex-log/codex-tui.log. Both tests involve the model and I did not run them.

What to write in a good AGENTS.md

/init generates a draft, but the Best practices page warns that it must be reviewed to reflect the way your team builds and verifies the project. A useful file answers, according to that page, questions of this kind:

  • How the repository is laid out and which folders matter.
  • How to run the project and what the build, test and lint commands are, written in full.
  • Which conventions and which PR expectations cannot be read from the code.
  • Which constraints and which "do nots" apply.
  • What "done" means and how it is verified.

No item prevails over the others, but to these I would add a section that the page does not list: the traps that have already cost someone on the team time, because they are the only information the code does not contain. Writing "run the tests" is no use; writing the exact command and the way it fails when a dependency is missing, is. The following scheme is an example of mine to adapt, I did not give it to Codex and it was not run.

# AGENTS.md (scheme to adapt)

## Build and test
- Install: `pnpm install`
- API tests: `pnpm --filter api test`
- Lint is part of "done": `pnpm lint` must pass.

## Conventions
- TypeScript strict; no `any` without a comment explaining why.
- One commit per logical change, format `type(scope): subject`.

## Do not touch
- `src/generated/`: regenerated with `pnpm codegen`.
- The migrations already in `db/migrations/`: add a new one instead.

## Known traps
- Integration tests require Postgres on localhost:5432; without it, they fail by timeout and not with a clear error.

What not to write: generic descriptions such as "write clean code", what the model already knows, and above all any security rule that the program does not enforce. If a sentence begins with "you must never", ask yourself whether it belongs in config.toml or in a check script. For code review on GitHub the documentation provides a ## Code Review Rules section in the AGENTS.md closest to the code concerned: repository rules at the root, service rules in a nested file.

config.toml: where it lives and who wins

The documentation indicates three locations:

  • User: ~/.codex/config.toml.
  • Project: .codex/config.toml in the repository or in a subfolder, loaded only if the project is trusted.
  • System (Unix): /etc/codex/config.toml, if present.

From these three locations, plus the command line and the profiles, an exact precedence arises; the surprising point is that the project file beats your user file. It is useful in a team, because the repository imposes its rules, and it explains why the same command behaves differently in two folders. From the highest to the lowest, according to the "Config basics" page:

  1. Command-line options and --config overrides (-c key=value).
  2. The project files .codex/config.toml, from the root to the current folder: the closest wins, only for trusted projects.
  3. The profile file chosen with --profile name, that is ~/.codex/name.config.toml.
  4. The user configuration, ~/.codex/config.toml.
  5. The values managed by the cloud, when delivered to your workspace.
  6. The system configuration.
  7. The built-in default values.

Here the order is everything, and the list is already an algorithm: for each key, Codex takes the value of the first level that defines it, from the top. If you do not understand why a setting does not have the effect you expected, the CLI's /debug-config command prints the configuration layers in order, with their active status and the sources of the policies; it is the first thing to look at and I did not run it. Two constraints on the project level: Codex ignores in a project .codex/config.toml the keys that redirect credentials or providers (the page lists openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url and otel) and prints a warning at startup; and an untrusted project loses its .codex/ layers altogether, including local rules and hooks.

A shape validator and a precedence resolver

Before putting a config.toml in a repository, it is worth knowing whether it contains values that the program rejects. The following script checks only the keys that I list, with the values allowed by the "Configuration Reference" page: approval_policy (on-request, never or the granular table; untrusted is retired and on-failure deprecated), sandbox_mode, web_search (cached, indexed, live, disabled), the conflict between default_permissions and sandbox_mode, and the keys that a project file cannot set. All the other keys are declared "unchecked". The resolve function applies the precedence between two levels (project above user) with a simplification of mine: tables replace each other, while the page says the environment filters merge across levels. The printed words ERROR and WARNING classify each finding.

"""A shape check for config.toml, and who wins between two levels.

The allowed values are those of the "Configuration Reference" page and of the pages
"Config basics" and "Agent approvals & security" (consulted on 2026-11-13). It checks
ONLY the keys listed below: it declares all the others unchecked.
It is not Codex and does not replace its error message at startup.
"""
import sys, tomllib

SANDBOX = {"read-only", "workspace-write", "danger-full-access"}
WEB = {"cached", "indexed", "live", "disabled"}
GRANULAR = {"sandbox_approval", "rules", "mcp_elicitations", "request_permissions", "skill_approval"}
# Keys that a project .codex/config.toml can NOT set (Codex ignores them and warns).
IGNORED_BY_PROJECT = {"openai_base_url", "chatgpt_base_url", "apps_mcp_product_sku",
                      "model_provider", "model_providers", "notify", "profile",
                      "profiles", "experimental_realtime_ws_base_url", "otel"}
CHECKED = {"approval_policy", "sandbox_mode", "web_search", "default_permissions",
           "project_doc_max_bytes", "model", "model_reasoning_effort", "profile", "profiles"}

def check(cfg, project=False):
    issues = []
    ap = cfg.get("approval_policy")
    if ap == "untrusted":
        issues.append("ERROR approval_policy = 'untrusted' is retired: it can prevent startup")
    elif ap == "on-failure":
        issues.append("WARNING approval_policy = 'on-failure' is deprecated: use on-request or never")
    elif isinstance(ap, dict):
        extra = set(ap.get("granular", {})) - GRANULAR
        if "granular" not in ap or extra:
            issues.append(f"ERROR approval_policy table not valid, keys: {sorted(extra) or 'granular missing'}")
    elif ap not in (None, "on-request", "never"):
        issues.append(f"ERROR approval_policy = {ap!r} is not a documented value")
    if cfg.get("sandbox_mode", "read-only") not in SANDBOX:
        issues.append(f"ERROR sandbox_mode = {cfg['sandbox_mode']!r} is not documented")
    if cfg.get("web_search", "cached") not in WEB:
        issues.append(f"ERROR web_search = {cfg['web_search']!r}: allowed {sorted(WEB)}")
    if "default_permissions" in cfg and "sandbox_mode" in cfg:
        issues.append("ERROR default_permissions and sandbox_mode together: the Permissions page says 'not both'")
    sep = cfg.get("shell_environment_policy", {})
    if ({"exclude", "include_only"} & set(sep)) and "filters" in sep:
        issues.append("ERROR shell_environment_policy: exclude/include_only and filters in the same level")
    if {"profile", "profiles"} & set(cfg):
        issues.append("WARNING profile/profiles: not read since 0.134.0; use ~/.codex/<name>.config.toml")
    if project:
        for key in sorted(IGNORED_BY_PROJECT & set(cfg)):
            issues.append(f"WARNING {key}: ignored in a project config.toml")
    return issues

def resolve(levels):
    """levels: [(name, dict)] from strongest to weakest; returns key -> (value, name)."""
    out = {}
    for name, cfg in reversed(levels):
        for k, v in cfg.items():
            if name.startswith("project") and k in IGNORED_BY_PROJECT:
                continue                      # Codex ignores it: it does not enter the effective value
            out[k] = (v, name)                # my simplification: tables replace each other (the page says the environment filters merge across levels)
    return out

if __name__ == "__main__":
    loaded = {}
    for path in sys.argv[1:]:
        with open(path, "rb") as f:
            loaded[path] = tomllib.load(f)
        project = path.startswith("project")
        issues = check(loaded[path], project)
        unchecked = sorted(set(loaded[path]) - CHECKED - {"shell_environment_policy"})
        print(f"{path}: {len(issues)} findings; unchecked keys: {unchecked or 'none'}")
        for g in issues:
            print("  -", g)
    names = [n for n in loaded if n.startswith("project")] + [n for n in loaded if n.startswith("user")]
    if len(names) == 2:
        print("effective value (project beats user):")
        for k, (v, source) in sorted(resolve([(n, loaded[n]) for n in names]).items()):
            print(f"  {k} = {v!r}  <- {source}")

# Command: python3 -I valida_config.py user.toml project.toml errors.toml
# Output:
# user.toml: 0 findings; unchecked keys: none
# project.toml: 1 findings; unchecked keys: ['model_provider']
#   - WARNING model_provider: ignored in a project config.toml
# errors.toml: 5 findings; unchecked keys: none
#   - ERROR approval_policy = 'untrusted' is retired: it can prevent startup
#   - ERROR sandbox_mode = 'workspace_write' is not documented
#   - ERROR web_search = 'yes': allowed ['cached', 'disabled', 'indexed', 'live']
#   - ERROR default_permissions and sandbox_mode together: the Permissions page says 'not both'
#   - WARNING profile/profiles: not read since 0.134.0; use ~/.codex/<name>.config.toml
# effective value (project beats user):
#   approval_policy = {'granular': {'sandbox_approval': True, 'rules': True, 'request_permissions': False}}  <- project.toml
#   model = 'gpt-6.1-sol'  <- user.toml
#   model_reasoning_effort = 'medium'  <- user.toml
#   sandbox_mode = 'read-only'  <- project.toml
#   shell_environment_policy = {'inherit': 'core', 'ignore_default_excludes': False, 'filters': {'AWS_*': 'exclude'}}  <- user.toml
#   web_search = 'cached'  <- user.toml

The three test files that the script reads are the following; user.toml and project.toml are plausible configurations, errors.toml gathers typical errors, and all three are schemes to adapt, not given to Codex. In the effective value the project imposes sandbox_mode = "read-only" and a granular approval policy, while the model and the reasoning level remain the user's; the project's model_provider is discarded, as the documentation says. The model name in user.toml is the one from the official example: check the Models page before copying it.

# ===== user.toml =====
model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"
web_search = "cached"

[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"

# ===== project.toml =====
sandbox_mode = "read-only"
approval_policy = { granular = { sandbox_approval = true, rules = true, request_permissions = false } }
model_provider = "internal"

# ===== errors.toml =====
approval_policy = "untrusted"
sandbox_mode = "workspace_write"
web_search = "yes"
default_permissions = ":workspace"
profile = "review"

In the output, errors.toml produces four errors and a warning: untrusted (retired), workspace_write with the underscore in place of the hyphens (a typo nobody notices by eye), yes as the value of web_search, the pair default_permissions with sandbox_mode that the permissions page forbids, and profile, which since 0.134.0 is no longer read (profiles live in ~/.codex/name.config.toml files). The limit of the validator is sharp: it checks the shape of a few keys and does not know whether the model exists, whether your version accepts them or whether an administrative level forbids them. It serves for the typo, not for certainty.

A reasonable team setup

A repository can contain an AGENTS.md at the root and a .codex/config.toml that fixes prudent sandbox and approval, so that every colleague starts from the same behavior. A security detail worth knowing: in the default workspace-write sandbox, the .codex folder inside a writable workspace is protected as read-only, so the agent cannot rewrite the project configuration by itself. The cost is twofold: the project file applies only to trusted projects (it has to be explained to newcomers) and it must be reviewed like any other file. Treat it as you would treat a change to the CI pipeline: it changes what a process can do with your permissions. Every change to .codex/config.toml deserves the same look as a change to a workflow.

For one-off tests there is no need to touch the file: codex -c log_dir=./.codex-log overrides the key for that single run, and experimental features are turned on with codex --enable feature_name or with feature_name = true under [features]. Model names change continuously: the official example uses gpt-6.1-sol, but the Models page specifies that it must be chosen among those available to your account or workspace.

Frequently asked questions

Where do I put a rule that must always hold?

In config.toml, not in AGENTS.md. A natural-language instruction can be followed badly; a configuration value such as sandbox_mode or approval_policy is applied by the program. If the rule concerns a command, part 3 shows the command rules.

Why does Codex seem to ignore my AGENTS.md?

The causes listed by the documentation are: an empty file (Codex skips empty files), an AGENTS.override.md higher up or in the Codex home folder that takes the place of the one you edited, a misspelled fallback name, the byte cap reached, and a CODEX_HOME variable that points to another folder. Restart Codex after every change: there is no cache to empty, because the chain is rebuilt at every startup.

Does the repository's config.toml beat mine?

Yes, if the project is trusted: in the precedence the project file sits above the profile and your user file, and the one closest to the working folder wins among several project files. If the project is not trusted, Codex ignores its .codex/ layers.

What you can do now

You can tell advice from a constraint and put them in the right place, predict which instruction files enter the chain and which one is left out when the cap is reached, write an AGENTS.md that answers a few questions instead of describing everything, and read the precedence of config.toml as an algorithm that you can simulate. The next step concerns the costs of what you have configured: part 5 on models, reasoning and costs explains how to choose the model and the reasoning level. For the permissions you have just put in the configuration, part 3 is the reference, and part 2 shows the first task.

What I did not verify

I did not run Codex, so I verified neither that the instructions are read in the order described nor whether the byte cap applies to the sum or to each file: the documentation describes it in two ways and the model follows only one reading. I did not try /debug-config, --cd or log_dir. The two programs check only what they declare and replace neither the reading of the page nor the warning that Codex prints at startup.

The same series also includes the product map (part 1), cloud, subagents, skills and MCP (part 7) and the comparison with Claude Code, Copilot and Cursor (part 8).

Sources

  • Custom instructions with AGENTS.md - search chain, override, fallback names, 32 KiB cap, troubleshooting of discovery; consulted on 2026-11-13
  • Config basics - file locations, order of precedence, main keys, shell_environment_policy, log_dir, experimental features; consulted on 2026-11-13
  • Advanced Configuration - project files, keys ignored in a project file, profiles and the change from 0.134.0; consulted on 2026-11-13
  • Configuration Reference - allowed values of sandbox_mode, approval_policy, web_search, project_doc_max_bytes; consulted on 2026-11-13
  • Best practices - what a good AGENTS.md contains, /init as a starting point; consulted on 2026-11-13
  • Agent approvals & security - protected paths in the workspace, untrusted retired; consulted on 2026-11-13

The two programs (catena_agents.py and valida_config.py) are my own models of the documented rules: run twice with Python 3.14 on Linux, same output. The AGENTS.md and the TOML files shown are schemes to adapt, not given to Codex.

← Part 3: sandbox and approvals Part 5: models, reasoning and costs →

Commenti

Caricamento commenti...

Sign in to comment

New articles and tools on Telegram too

The Telegram channel flags the site's new articles and tools.

Did you like this article?

Explore other content on the blog or discover my projects