AGENTS.md
AGENTS.md is a Markdown file that the agent reads at the start of every conversation. Put in it what you would otherwise repeat in every prompt: how the code is laid out, how to build and test it, and what not to touch.
It follows the open AGENTS.md convention, so the same file works with other coding agents. The CLI, the VS Code extension and the Desktop app all read it.
Where it goes
Create AGENTS.md in the root folder of your project. That is all. No setting to change, no restart.
my-project/
├── AGENTS.md ← read at the start of each conversation
├── src/
│ └── AGENTS.md ← listed by path; read when the agent works here
└── package.json
Which files load
These are sent at the start of a conversation, in this order, each followed by the files it pulls in:
| File | When |
|---|---|
~/.abacusai/AGENTS.md | Always, in every project |
AGENTS.md and AGENTS.local.md at the git root | When you are inside a repository |
AGENTS.md and AGENTS.local.md in the folder you opened | When it is not already the git root |
They share one budget, and each is labelled with the directory it covers, or for a file pulled in, the file that named it. Open a session in repo/packages/foo and the repository's root rules arrive along with that package's, root first.
The repository's other AGENTS.md files are not loaded. Their paths are listed after the loaded ones, so the agent can open the file covering a directory before it works there. Keeping intermediate files to a list rather than loading them all is what keeps the instruction text small.
The git root is the nearest folder above you holding a .git entry. A linked worktree or a submodule stops that search at its own root. The listed paths come from git's index, so an ignored AGENTS.md is left out. Outside a repository, only the folder you opened is read.
Keep the root file short and put area-specific detail next to the code it describes.
A file for every project
~/.abacusai/AGENTS.md holds the instructions you want everywhere: your review habits, a language preference, tools you always want used. It loads alongside each project's file rather than replacing it.
If you have no user-level file, nothing about a project's AGENTS.md changes: when it is the only file, with no AGENTS.local.md and nothing pulled in, it is sent exactly as written, with no labels around it.
Personal notes for a project
AGENTS.local.md sits beside a project's AGENTS.md and is sent after it. Use it for instructions that are yours alone, such as your local URLs or how you like to work in this repository. Add it to .gitignore so it stays out of commits.
Pulling in other files
A file can name another with @ and its path, and that file is sent too:
See @docs/architecture.md for how the services fit together.
My review habits: @~/notes/review.md
A path is relative to the file that names it, ~/ starts at your home folder, and an absolute path is used as written. A file pulled in can name others in turn, up to five levels deep. An @ that does not name an existing file stays plain text, as does one inside a code block or inline code, so @user and email addresses are left alone.
Until you trust the folder, a project's files can only pull in files inside the project. Your own ~/.abacusai/AGENTS.md can pull in any file.
What to put in it
# Acme Web App
## Stack
- TypeScript + React (Vite), Tailwind for styling.
- Backend: Python (FastAPI) under `server/`.
## Conventions
- Functional components and hooks only. Named exports.
- 2-space indentation, single quotes.
## Build and test
- Install: `npm install`
- Dev server: `npm run dev`
- Before finishing any task: `npm run lint && npm run typecheck`
- Tests: `npm test`
## Don'ts
- Never edit files under `src/generated/`. They are generated.
- Don't commit `package-lock.json` changes unless a dependency changed.
What makes the file work well:
- Lead with the rules the agent must not miss.
- Spell out exact commands. The agent runs them to check its own work.
- Prefer short bullets to prose.
- Update it when conventions change, and review it in pull requests like code.
How it is used
The files are read when you send the first message of a conversation and stay with that conversation. Edits show up in your next new conversation.
The loaded files share one 40,000-character budget. Past it the text is cut, with a note naming every file that was meant to be there, so one pushed out by the cap can still be found and read from disk. Well under that is plenty.
Switching folder in the Desktop app or CoWork reloads them, so the previous repository's rules never carry into the next one. Blank files are skipped, and a file that is both your git root's and your workspace's is sent once.
Turn it off
| Where | How |
|---|---|
| One CLI session | abacusai --no-agents-md |
| CLI | /settings, then switch off "Load AGENTS.md" |
| VS Code | Abacus Settings, Agent & permissions section, "Auto-load AGENTS.md" |
config.json | "autoLoadAgentsMd": false |
| Environment | ABACUS_AUTO_LOAD_AGENTS_MD=false |
See Settings for how these combine.
AGENTS.md, skills or settings?
| You want to | Put it in |
|---|---|
| Describe the project, its conventions and its commands | AGENTS.md |
| Package a repeatable procedure, loaded only when it is relevant | A skill |
Enforce something rather than ask for it, such as never reading .env | A permission rule in Settings |
| Give the agent access to an external service | An MCP server |
For further help, reach out at support@abacus.ai.