Project instructions
Create an AGENTS.md in your project root with the commands and conventions fx should follow:
# Project instructions
- Run `npm test` after changing application code.
- Reuse components from `src/components`.
- Regenerate API clients from the schema instead of editing them.
Instruction sources
fx reads AGENTS.md from the directory where you start it. For projects under your home directory, it also reads parent directories' AGENTS.md files up to, but excluding, your home directory.
Use ~/.fx/AGENTS.md, or $FX_HOME/AGENTS.md when you set FX_HOME, for personal instructions across projects. It can be a link to a file elsewhere in your home directory, such as one in a dotfiles repository. Your prompts take priority over instructions in these files.
Any other AGENTS.md can be a link only to a file inside its own folder, such as a CLAUDE.md beside it. fx skips a link that points anywhere else.
Instructions for a subdirectory
A nested AGENTS.md adds instructions for that part of the project:
project/
├── AGENTS.md
├── apps/
│ └── web/
│ ├── AGENTS.md
│ └── src/
└── packages/
When fx works on a file in apps/web/src/, it loads apps/web/AGENTS.md alongside the root instructions. If they conflict, the instructions closest to the file take precedence.
fx adds a folder's instructions the first time a tool call reaches that folder, such as reading, searching, or editing a file there. When a later turn returns to the folder, fx reminds the model that those instructions still apply. fx loads these files only inside the primary workspace.
Missing instructions
fx shortens or leaves out instructions in these cases:
- A file longer than
project_instruction_file_bytes, 64 KiB by default, is cut at its last complete line within the limit. - When the combined instructions pass
project_instructions_total_bytes, 128 KiB by default, fx leaves out whole files. It keeps your personal instructions first, then the file closest to the work, then any others that still fit. - When more than 32 folder
AGENTS.mdfiles apply at once, fx loads the 32 closest to the work. - fx skips a file that is empty, isn't valid UTF-8, or is larger than 64 MiB, and a link that points outside the places Instruction sources allows.
See context limits to change the two size limits.
Additional directories give fx access to files, but do not load those directories' AGENTS.md files or configuration.
Disable project instructions
To stop loading AGENTS.md files automatically, including your personal instructions, set context to false in the project's .fx.json:
{
"context": false
}
You can also set it in ~/.fx/settings.json. See Configuration for how the files combine.