Skip to main content
Project instructions are Markdown files that o4 adds to the model’s system prompt at the start of every session. Use them for what the model should always know about a project: how to build and test it, its conventions, and what to avoid. o4 reads the common AGENTS.md convention, so a repository set up for other coding agents works without changes.

​
Which files o4 reads

o4 looks for these files in the directory you start it in (or the one you pass with -C): It also reads your personal instructions from ~/.o4/instructions.md, which apply to every project. All the files that exist are used. None replaces another. o4 reads these files only from that one directory. It doesn’t look in parent directories or subdirectories, so an AGENTS.md in a subfolder is ignored. If you start o4 in a subdirectory of a repository, the files at the repository root aren’t read. Start o4 at the root, or pass the root with -C.

​
How they reach the model

o4 puts the instructions near the end of the system prompt, in two sections:
  1. User Instructions: the content of ~/.o4/instructions.md. The prompt tells the model these may be overridden by the project instructions.
  2. Project Instructions: the content of the project files, joined in the order AGENTS.md, CLAUDE.md, .o4.md, .o4/instructions.md. The prompt tells the model these take precedence over user instructions and o4’s defaults.
o4 doesn’t merge or deduplicate the files. If AGENTS.md and CLAUDE.md contain the same text, the model sees it twice. To keep a single copy, make one file refer to the other, or keep the shared guidance in only one of them. You can see exactly what o4 sends with --print-system-prompt, which prints the assembled system prompt and exits without calling a model:
Besides these files, the system prompt includes some context o4 gathers on its own: recent git commits, the project’s folder structure, and the start of key files such as README.md, Cargo.toml and package.json.

​
Limits

  • o4 reads up to 50 KB of each instruction file. It cuts a longer file at that point and adds a warning to the system prompt, such as [WARNING: instruction file truncated at 50KB limit: /path/to/AGENTS.md].
  • A file that isn’t valid UTF-8 is skipped with a warning.
  • A project instruction file that is a symlink to somewhere outside the project is skipped.
Instruction files are read whether or not the workspace is trusted, since they are text for the model and can’t run anything. Hooks in .o4.md are the exception: they run only in a trusted workspace. The whole of .o4.md, including its hooks blocks, still goes to the model as instructions.

​
Create an AGENTS.md with /init

Run /init to have the model write the project’s instructions for you. o4 asks the model to study the repository (its build files, CI config, README and any existing instruction files, including .cursorrules and .github/copilot-instructions.md) and create or improve AGENTS.md at the project root. It edits only AGENTS.md. If the file already exists, the model makes targeted improvements instead of replacing it. The model uses its normal tools to do this, so file edits go through the usual permission prompts.

​
Reload after editing

o4 reads instruction files when a session starts. After you edit them, run /reload to read them again and rebuild the system prompt in the current session. With auto memory on (the default), /reload also reloads memory and shows Reloaded project instructions and memory.; otherwise it shows Reloaded project instructions. If the model is working, /reload waits until the turn finishes.

​
Writing good instructions

Keep instructions short and specific to the project. Each line costs context on every request. Good candidates are the commands to build, test and lint, conventions the code doesn’t make obvious, and mistakes to avoid. See Writing prompts for more on giving the model useful context, and Memory for notes o4 keeps between sessions on its own.