> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Project instructions

> Give o4 standing instructions for a project with AGENTS.md and related files.

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`):

| File | Notes |
| - | - |
| `AGENTS.md` | The shared convention used by many coding agents. `/init` creates this one. |
| `CLAUDE.md` | Read too, so a repository set up for Claude Code works as is. |
| `.o4.md` | An o4-specific file. It can also define [hooks](/extend/hooks). |
| `.o4/instructions.md` | An o4-specific file inside the project's `.o4` folder. |

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:

```bash theme={null}
o4 --print-system-prompt | less
```

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](/safety/workspace-trust), 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](/safety/permissions) 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](/guides/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](/guides/prompting) for more on giving the model useful context, and [Memory](/guides/memory) for notes o4 keeps between sessions on its own.