AGENTS.md and /init

An AGENTS.md is a Markdown file of instructions that Tatu reads at the start of every session: how to build and test the project, what to avoid, how you like things done. The model sees it as part of its system prompt, so you write it once instead of repeating it.

To get a first version, ask Tatu to write it:

/init

Or write one yourself, in the root of the project:

# Notes for the agent

## Commands
- Build: `make build`
- Test everything: `make test`; one package: `go test ./internal/config`
- Lint before you finish: `make lint`

## Conventions
- Errors are wrapped with `fmt.Errorf("...: %w", err)`.
- Never edit files under `generated/`; run `make generate` instead.

## Gotchas
- The integration tests need Docker and take about two minutes.

Where Tatu looks

Tatu reads these places, in this order:

AGENTS.md in ~/.tatu (or in the folder TATU_HOME points to). It is yours and applies to every project.
AGENTS.md in each folder from the top of the disk down to the folder you started Tatu in, the folder you run Tatu from last.

In each folder, Tatu uses AGENTS.md; if there is none, it uses CLAUDE.md. It never reads both from the same folder. The files are added to the system prompt in the order above, so the closest file comes last, and Tatu is told that a later file wins over an earlier one when they disagree.

This lets you keep personal habits in ~/.tatu/AGENTS.md and the rules of a monorepo in its root.

Tatu reads those files when it starts, and the files they import. The welcome card shows how many it loaded, imports included (for example 2 context files).

Files in subfolders

A big project does not need one giant file at its root. Put an AGENTS.md (or CLAUDE.md) in a subfolder, such as services/api/, and Tatu gives it to the model the first time read, write or edit touches a file in that folder or below it. The file is added to the result of that call, after the tool’s own text, so the model gets the rules of that part of the project at the moment it starts working there. The files of the folders in between come first, the outermost one first.

Each file is given once per conversation. A new conversation (/new, /resume, /fork), and a conversation after /compact or an automatic compaction, start over: the next call in that folder gives the file again.
Tatu shows a dim line under the tool block, such as + services/api/AGENTS.md, for each file it gave.
It looks only at folders below the folder you started in, and not through a link that leads out of it. The folders from the one you started in upward are in the system prompt from the start, as above.
A file imported with @path follows its importer, as in the system prompt. Each file is cut at 32 KiB, and all the subfolder files of a conversation together are held to 96 KiB; one that would go over is left out, and the result says so.
A subagent starts with none of these given and gets the files of the folders it works in, on its own.
bash is not looked at: running cd services/api && make test gives nothing. Reading or editing a file in the folder does.
-no-context-files and "contextFiles": false turn this off too.

Because the file arrives with the first call, a write or edit that is the first to touch a folder has already happened when the model sees the rules; a read first gives them before the change.

Imports

A file can bring in other files with a reference that starts with @, the way Claude Code does. The reference can be anywhere in the text:

# Notes for the agent

Read @docs/rules.md before you change the API.
My own habits live in @~/notes/tatu.md.

The path goes to the first space. To use one with spaces, put a backslash before each space (@Design\ Docs/api.md). A path that starts with ~ is in your home folder; any other path that is not absolute is relative to the folder of the file that holds the reference, not the folder you started Tatu in. A reference inside backticks or a fenced code block is not imported, so write `@docs/rules.md` to mention a path without reading the file.

An imported file becomes a section of its own in the system prompt, right after the file that imports it, and it can import other files: four levels of imports at most. A file that was already loaded is not read again, so a shared file imported from two places appears once. Imported files are instruction files like the rest: each is cut at 32 KiB, they share the 96 KiB limit, and one that is missing or is not text gets a note at startup instead of stopping Tatu. Any text file works, not only Markdown: @README.md, @docs/api.md and @Makefile all load.

Limits

Each file is cut at 32 KiB. Tatu marks the cut with [file truncated] and shows a note at startup.
All files together are held to 96 KiB. When they go over, Tatu drops the outermost files first, the most general ones, and keeps the closest. A note names each file it dropped.
An empty file, or one that is not text, is skipped. A note says so when it is not text.

To start without them, run tatu -no-context-files, or set "contextFiles": false in your settings.

What is worth writing

Write what a newcomer could not learn from reading a file or two:

exact commands to build, run, test and lint, and how to run a single test;
how the code is organized, in a few lines;
conventions that are easy to break, and files that must never be edited by hand;
gotchas that cost someone an afternoon: environment quirks, slow or flaky tests, order of steps.

Leave out generic advice (“write clean code”), a tour of every file and anything the model can find by itself. A short file that is right works better than a long one. Tatu’s own /init asks for about 80 lines.

/init

/init sends the model a request to look at the project (README, build files, tests, layout) and write an AGENTS.md at its root. If the project already has an AGENTS.md or a CLAUDE.md, the model reads it and improves it instead of replacing it. At the end it tells you what it wrote and what it was unsure of.

Add a focus after the command to steer it:

/init the build and the release process

Read the result before you rely on it: the model writes only what it found in the files, but it can still get something wrong. /init also works in print mode (tatu -p "/init").