Settings

Settings are JSON files. One is yours and applies everywhere; another can live in a project. You can edit them by hand, or change the common ones from the /settings panel inside Tatu.

{
  "provider": "anthropic",
  "model": "claude-opus-5-5",
  "effort": "high",
  "thinking": true,
  "subagents": {
    "fast": { "model": "deepseek/deepseek-flash", "effort": "low" }
  }
}

Save this as ~/.tatu/settings.json and the next session starts on that model, with the model’s reasoning shown, and subagents of the fast tier run on the DeepSeek model.

The two files

File	Applies to
`~/.tatu/settings.json`	every project. If you set `TATU_HOME`, it is `settings.json` in that folder.
`.tatu/settings.json` in a project	that project only.

A file that does not exist, or is empty, is fine. Both are plain JSON: no comments and no trailing commas.

The order of precedence, from the strongest:

a flag on the command line, for that run (-model, -effort, -thinking, -system, and so on);
the project’s file;
your global file;
the built-in default.

Settings combine key by key. If the global file sets model and effort and the project’s file sets only effort, you get the global model and the project’s effort. Inside an object such as compaction or subagents, the same rule applies field by field. A list such as web.search is replaced as a whole, not added to.

A session you resume goes back to the last model and effort it used, whatever the settings say. When no flag, session or file picks a model, Tatu uses the first provider you have a credential for.

Unknown keys are an error

Tatu does not guess. A key it does not know, a value that is not valid, or a file that is not JSON stops Tatu from starting, and the message names the file:

tatu: /home/ana/project/.tatu/settings.json: json: unknown field "permissions"

This catches typos ("modle"), and it means you cannot copy a settings file from another tool as it is. See Coming from Claude Code.

The /settings panel

Type /settings to open the panel. Each row shows the value in force, where it comes from and what it does. The origin is one of:

Origin	Meaning
`default`	nothing sets it; this is Tatu’s own value
`global`	it comes from `~/.tatu/settings.json`
`project`	it comes from the project’s `.tatu/settings.json`, which wins over the global file
`flag`	it comes from a flag of this run

Use the arrow keys to move and Enter to flip a switch or open a list of choices. Subagents and Daemon open a second panel. A change takes effect at once and is saved in your global file. The rest of that file is kept, and Tatu creates the file if it does not exist. Ctrl+R on a row puts it back to its default, which removes the key from the file. Esc goes back one level.

A setting that the project’s file sets is shown dim and cannot be changed from the panel, because that file belongs to the project and wins. Change it in the file.

You can also type the change. /settings thinking on does the same as the panel, and /settings thinking unset goes back to the default. /settings followed by a setting name and nothing else describes it.

The settings people change most

Setting	What it does
`provider` and `model`	the model new sessions start with. In the panel it is one row, Default model, and choosing it also switches the session you are in.
`effort`	how hard the model thinks: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` or `default`. Set with `/effort`.
`thinking`	`true` shows the model’s reasoning.
`saveDefaults`	when on (the default), what you pick with `/model` and `/effort` becomes the default for new sessions.
`subagents`	the model and effort of the `fast` and `balanced` subagent tiers.
`vision`	a model that describes images for a model that takes none. It needs both `provider` and `model`.
`autoName`	how new sessions are named: `off`, `session` (the model in use, the default) or `<provider>/<model>`.
`compaction.auto`	compact the conversation by itself when the context fills up (on by default).
`contextFiles`	`false` stops Tatu from loading AGENTS.md files.
`system`	extra instructions added to the system prompt.
`modelFamilies`	place a model in a family of the instructions Tatu writes for it. See Model families.
`hooks`	commands Tatu runs around tool calls. See Hooks.

Every setting, with its default, is in the settings reference. The panel shows the settings it can change. The others (such as system, contextFiles, the token limits and hooks) you change in the file.

Model families

Tatu writes its instructions to the model for the model that reads them. Most of the text is the same for every model. A short section, “How to work”, is added for the family a model belongs to, because models of different makers work differently with the same tools. Today there are two families: gpt, for OpenAI’s GPT and reasoning models (ids such as gpt-6.1-sol or o3, also when a router like OpenRouter serves them), and default, which adds nothing. Every other model is in default and gets the instructions it always had.

When you change the model with /model, the instructions are written again for the new one, so the section follows the model in use.

If Tatu does not recognize a model, such as one you run locally under a name of your own, place it with modelFamilies:

{
  "modelFamilies": {
    "my-local-gpt*": "gpt",
    "openai/gpt-oss*": "default"
  }
}

Each key is a pattern for the model id, or for provider/id, where * stands for any text without a /. Each value is gpt or default. The longest pattern wins when several fit. The project’s file adds to the global one, and wins for a pattern both set. An unknown family is an error that names the file. The /settings panel lists modelFamilies and where it comes from, but you change it in the file.

Daemon settings

daemon.mode and daemon.root describe the computer, not a project: when the daemon starts, and which folder it opens sessions in. Only your global file sets them. If a project’s file has a daemon section, Tatu ignores it and says so at startup:

this project's settings.json sets "daemon", which only /home/ana/.tatu/settings.json sets: ignored

See The daemon and worktrees.