Give Codex Instructions and a Working Directory

The rules that matter in an eval repository, such as "never edit the frozen eval set" or "report every score with its sample size", are ones an agent must not learn by breaking them. And the runs that matter most, a nightly eval or a sweep, start from a script, in whatever directory the scheduler picks.

In Lesson 1 you typed every rule into the task. That works once. Next time you forget one, or someone runs the task from another folder.

Two things make a Codex task repeatable: the rules live in the repository, and the directory Codex works in is stated, not inherited. You set up both on the stand-in repository from Lesson 1; the eval-repository version follows, written out but not yet run. You also ask a run what instructions it received, and see what that answer does not prove.

How Codex finds its instructions

OpenAI's documentation says "Codex reads AGENTS.md files before doing any work," and that it builds the list once per run. The order matters, so here it is in the documentation's own terms.

First, a global file: in your Codex home directory, ~/.codex by default, Codex "reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md."

Then the project: "Starting at the project root (typically the Git root), Codex walks down to your current working directory." In each directory on that path it takes at most one file, checking AGENTS.override.md before AGENTS.md.

Last, the merge: files are joined "from the root down," and "files closer to your current directory override earlier guidance because they appear later in the combined prompt."

Which instruction files a run loads, in order. ~/.codex: AGENTS.override.md, otherwise AGENTS.md; Project root: at most one file; Each folder on the way down: at most one file; The working directory: at most one file; Search stops here. Folders below are never read — Which instruction files a run loads, in order

Two consequences follow, and both surprise people. Codex does not read every AGENTS.md in the repository, only the ones on the path to where it is working. And the documentation says it "stops adding files once the combined size reaches the limit," 32 KiB by default, so a very long set of instructions can silently push the last file out.

Write the repository's instructions

Files changed

AGENTS.md

Put the rules you typed last time into a file

In the tip-splitter folder, create AGENTS.md with the rules from Lesson 1's task, written once:

markdown

# tip-splitter

- Every amount is a whole number of U.S. cents. Never use floats for money.
- Run the tests with `python -m unittest`. Every existing test must keep passing.
- Use only Python's standard library. Do not add dependencies.
- Change only what the task asks for. If something else looks wrong, say so and leave it.

Keep it this short. Each line is something a person would otherwise have to repeat.

Ask what Codex received

Do not assume the file is being read. Ask, in a run that cannot change anything:

bash

codex exec --sandbox read-only \
  "List the instruction sources you loaded, in order, and quote the rule about money."

--sandbox read-only is what keeps this run from editing. When I ran this in my copy of the folder, named tipsplit-run, Codex answered:

text

Loaded in order:

1. System instructions.
2. Developer instructions.
3. User-provided `AGENTS.md` instructions for `tipsplit-run`.
4. User-provided environment context.

The money rule in `AGENTS.md` is:

> Every amount is a whole number of U.S. cents. Never use floats for money.

No instruction files or skills were opened with tools.

This shows the rule reached the model: the task did not contain it, and Codex quoted it word for word. It does not show where the rule came from. Codex calls it "user-provided" and says it opened no files. The documentation says Codex itself adds AGENTS.md to the prompt, which would look like this to the model, but a model's account of its prompt is not a record of what the program did. This run does not establish that the rule came from the repository's file.

Two checks would; this course has not run either yet. The log: start Codex with -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log (the supplied .gitignore keeps that folder out of commits). The control: change the money rule in AGENTS.md to a sentence found nowhere else, rerun, and see whether the quote changes with it. The note Check Which AGENTS.md Files Codex Loaded Before Adding Rules covers three reasons a rule goes missing.

Use codex exec, not bare codex, for a check like this. The interactive form needs a terminal: run it from a script or a pipeline and it stops with Error: stdin is not a terminal. I hit that on the first attempt.

State the working directory

So far you have started Codex from inside the folder. A scheduled job, a sweep script or a colleague will not: a job script on a cluster starts wherever the scheduler puts it. The --cd flag sets "the working directory for the agent before it starts processing your request," and because the instruction search walks down to that directory, it also decides which AGENTS.md files apply.

Use the non-interactive form, codex exec, with the full path to your copy:

bash

codex exec --cd "$HOME/tip-splitter" --sandbox read-only \
  "Do not edit anything. Report your working directory, the instruction sources you loaded, and the rule about money."

The documentation says codex exec "runs in a read-only sandbox" by default and "prints only the final agent message to stdout." Stating the sandbox anyway makes the command say what it means.

Run it from somewhere else

Run that same command twice, from two unrelated places:

bash

cd ~
codex exec --cd "$HOME/tip-splitter" --sandbox read-only \
  "Do not edit anything. Report your working directory, the instruction sources you loaded, and the rule about money."

cd /tmp
codex exec --cd "$HOME/tip-splitter" --sandbox read-only \
  "Do not edit anything. Report your working directory, the instruction sources you loaded, and the rule about money."

I ran both, against my tipsplit-run copy rather than $HOME/tip-splitter. Each reported the same workspace and the same rule, whether launched from my home directory or from /tmp:

text

- Working directory: `/private/tmp/.../scratchpad/tipsplit-run`
- Instruction sources loaded: system and developer instructions, plus the `AGENTS.md`
  instructions supplied in your message. No instruction files or skills were read from disk.
- Money rule: Every amount is a whole number of U.S. cents. Never use floats for money.

No files were edited.

Both runs agree on the working directory, which is what this step tests. The second line repeats the earlier caveat: Codex says the rules arrived in its prompt and it read nothing from disk. Only the log or the control shows where they came from.

If either run reports the folder you launched from, the command is not repeatable yet, and that is worth fixing before you let it write anything. Pin the Working Directory of a Scheduled Codex Run covers the scheduler case.

Commit the instructions

AGENTS.md is part of the repository now. Commit it, so the rules travel with the code:

bash

git add AGENTS.md
git commit -m "Add repository instructions for Codex"

What this gives you

The task from Lesson 1 no longer needs its rules spelled out. "Add a function that formats a list of shares as one line" is now enough, because whole cents, the test command, no new dependencies and "change only what was asked" arrived with every run here. Before you rely on that in an eval repository, run the log or the control check. And the command carries its own directory, so it behaves the same from a terminal, a script or a scheduler.

The same file in a research repository

This course has not run the example below. It shows what the rules of an eval repository could look like, written once so that no task has to repeat them:

markdown

# eval-harness

- Never edit anything under `data/frozen/`. Those files define the benchmark.
- Scoring lives in `score.py`. Change it only when the task names it.
- Every reported score states its sample size and a 95 percent interval.
- Randomness goes through the `--seed` option. Never hard-code a seed.
- Run the tests with `python -m unittest` before you report that you are done.

Each line guards a way a results table goes wrong without anything crashing: a benchmark file edited in passing, a scoring change nobody asked for, a number without its error bar, a run nobody can repeat. The second course in this track, evaluating coding agents, goes one step further: the check that judges the agent's work sits where the agent cannot edit it at all.

A rule in a folder below the working directory is never read

If you later add docs/AGENTS.md with documentation rules and run Codex from the repository root, those rules do not load: the search stops at the working directory. Start Codex in docs, or pass --cd docs, when you want them. The same holds for an evals/AGENTS.md in a research repository: it applies only to runs that work in evals or below.

What was checked

Executed on September 21, 2026 with codex-cli 0.155.1, signed in through a ChatGPT account: the instruction-listing command, and the two-directory trial from a home directory and from /tmp. The outputs above are copied in full from those runs, with only the scratch path shortened, and the full terminal output is in agent-run-lesson-02/ in the course materials. The discovery order, the override file, the 32 KiB default and the log option come from OpenAI's Codex documentation, read the same day; the flags also appear in codex --help. The documentation mentions a codex status command in one place; the CLI reference does not list it, so this lesson does not use it. Those runs show the money rule reached the model; they do not show it was read from the repository's AGENTS.md, and the log and control checks were not run. The eval-harness AGENTS.md was written for this page and has not been run.

Quick check — Your repository has AGENTS.md at the root and another in the docs folder. You run Codex from the repository root. Which files does it load from the project?

Next in the track: evaluate a coding agent

You can now get one checked change from Codex. The next course asks how you would know an agent does this well across many tasks: acceptance it cannot redefine, a fixed task set, and a pass rate with an error bar. Further lessons in this course, starting with what Codex may read, change and execute, appear on the course page as each is finished.