Project instructions (AGENTS.md)
Give Tau standing instructions about your project with AGENTS.md files.
An AGENTS.md file is how you give the agent durable, project-specific
context: conventions to follow, commands to run, things to avoid. Tau discovers
these files automatically and includes them in the system prompt for every turn,
wrapped in <project_context> tags.
What to put in it
Anything you’d otherwise repeat to the agent every session:
- how to run tests, lint, build, and format
- project conventions (style, commit message format, branch naming)
- architectural notes and gotchas
- “always do X / never do Y” rules
Keep it focused — it’s part of the prompt budget for every turn.
Where Tau looks
Tau discovers instruction files in this order. User files are always eligible; project files are included only after the active cwd’s [project-trust decision] (/guides/project-trust/):
~/.tau/AGENTS.md
~/.agents/AGENTS.md
<project root>/AGENTS.md
<project root>/.../<cwd>/AGENTS.md # ancestor dirs between root and cwd
<cwd>/.tau/AGENTS.md
<cwd>/.agents/AGENTS.md
The project root is the nearest ancestor directory containing a marker such
as .git, pyproject.toml, uv.lock, setup.py, or package.json.
This layering lets you keep personal global instructions in ~/.tau/ or
~/.agents/, project-wide rules in the repo’s AGENTS.md, and narrower rules in
a subdirectory closer to where you’re working.
Reloading after edits
If you change an AGENTS.md while the TUI is open, run /reload to refresh
project context for future turns. Adding the first protected file to an empty
project triggers trust resolution rather than silently inheriting the old empty
snapshot.