Custom subagents

A custom subagent is a helper the model can start for a certain kind of task. You describe it in a Markdown file; the model reads the description to decide when to use it. For what subagents are and how they run, see Subagents.

Save this as ~/.tatu/agents/reviewer.md:

---
description: Reviews a diff for bugs. Use after a change that touches several files.
tools: read, grep, find, bash
model: fast
---
You review code for bugs. Read the files that changed and the code that calls them.
Report only problems you can point to, each with a file and a line, and say how sure you are.
Do not change any file.

Start Tatu and ask for a review of your changes. The model can now start a reviewer subagent, which does its reading on a cheaper model and answers with a short report.

Where the files go

Folder	Applies to
`~/.tatu/agents/`	every project (`agents/` inside `TATU_HOME`, if you set it)
`.tatu/agents/` in a project	that project only

The file agents/<name>.md defines the type <name>. Only files that end in .md directly in the folder are read. Tatu reads them when it starts.

A project’s file replaces a global one with the same name. A file can also replace one of the two types that come with Tatu, general-purpose and explore; a note at startup says so.

The front matter

Field	What it does
`name`	the type’s name. Without it, the file’s name. Use lowercase letters, digits and single hyphens.
`description`	required. When to use this subagent. The model reads it to decide, so say what the agent does and when to call it.
`tools`	the tools it may use, separated by commas: `read, grep, find, bash`. Square brackets are fine too. Without it, the subagent gets all the tools below.
`model`	the model it runs on: `fast`, `balanced`, `main` or `inherit`, or `provider/model`. Without it, or with `main` or `inherit`, it uses the model you are using.

The text after the front matter is the subagent’s instructions. Tatu adds it to the base prompt that every agent gets, and the subagent also sees your AGENTS.md files. The text is cut at 32 KiB.

A file with no description, a name that is not valid or a model that is not one of the forms above is skipped, with a note at startup. A value such as model: sonnet is therefore not accepted; write balanced, or the full anthropic/claude-sonnet-5-5.

Write each field on one line, as key: value. Do not put a comment after a value: it becomes part of the value. Other fields are ignored.

Tools

The names are Tatu’s, written in lowercase:

Tool	What it does
`read`	read a file
`grep`	search inside files
`find`	find files by name
`bash`	run a command
`write`	create or replace a file
`edit`	change part of a file
`web_search`	search the web
`web_fetch`	fetch a web page

Without a tools line, a subagent gets all eight, and the tools of your MCP servers. It never gets ask_user, background tasks or the tool that starts subagents: it cannot ask you a question, cannot leave a command running and cannot start other subagents. Names that Tatu does not know are ignored. If none of the names exists, the subagent does not start and the model gets the error none of its tools (...) exists.

A tool of an MCP server is named mcp__<server>__<tool>, and a name in tools can be a pattern: tools: read, grep, mcp__github__* gives the subagent the file tools and every tool of the server github. A list without such a name gives it none of them.

To make a read-only agent, list only read, grep, find. Add bash only if it needs to run commands, as bash can change things. The explore subagent that comes with Tatu lists read, grep, find, bash and is told in its instructions not to change anything.

Choosing the model

fast, balanced and main are the tiers. fast is a small, cheap model for searching and reading, balanced a mid-size one for well-specified work, and main the model you are using. Which model a tier means comes from your settings (subagents) or, without them, from the provider you use.

A tier whose model has no credential falls back to your model, and Tatu notes it in its log.
A provider/model value does not fall back. If you are not signed in to that provider, the subagent fails to start and the model gets the error.
When the model starts a subagent it can still ask for a different tier for that call. That choice wins over the file.

Limits

The cost of a subagent is added to the session’s totals. Hooks for tool calls (PreToolUse and PostToolUse) also run for a subagent’s tool calls.