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
Three are sent at the start of a conversation, in this order:
| File | When |
|---|---|
~/.abacusai/AGENTS.md | Always, in every project |
AGENTS.md at the git root | When you are inside a repository |
AGENTS.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. 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: a lone file is sent exactly as written, with no labels around it.
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 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.