Settings reference
Settings files reject unknown keys; a project can contain settings and hooks, so read them before running Tatu in a clone.
| Key in JSON | Type | Default when omitted | Changeable with /settings? |
Global file only? | What it does | See |
|---|---|---|---|---|---|---|
provider |
String | First provider with a credential | Through /settings model |
No | Provider for new sessions. | Models |
model |
String | Provider’s default model | Yes, as provider/model |
No | Model ID for new sessions. | Models |
effort |
String | Model default | No; use /effort |
No | Reasoning effort: off, minimal, low, medium, high, xhigh, max or default. |
Models |
thinking |
Boolean | false |
Yes | No | Show the model’s reasoning. | Models |
maxTokens |
Integer | Provider’s default | No | No | Cap output tokens per response. | Models |
maxIterations |
Integer | 200 |
No | No | Cap model calls in one run. | Scripting |
system |
String | None | No | No | Add instructions to the system prompt. | Settings |
contextFiles |
Boolean | true |
No | No | Load AGENTS.md or CLAUDE.md instructions. |
AGENTS.md |
saveDefaults |
Boolean | true |
Yes | No | Save /model and /effort choices for new sessions. |
Models |
updateCheck |
Boolean | true |
No | No | Check for updates at startup, at most once a day. | Install and update |
terminalNotifications |
Boolean | true |
Yes | No | Send terminal notifications for questions, completed turns and errors. | Settings |
autoName |
String | session |
Yes | No | Name sessions using the session model; also accepts off or provider/model. |
Sessions |
modelFamilies |
Object mapping model globs to a family | None | No | No | Place a model in a family of the system prompt (default or gpt) when Tatu does not recognize it, or take it out of one; read from both files, the project’s winning for the same glob. |
Settings |
mascot |
String | auto |
Yes | No | Footer mascot rendering: auto, placeholders, direct, off. |
Settings |
motion |
String | full |
No | No | Mascot motion: full, reduced, static; read at startup. |
Settings |
compaction |
Object | Child defaults below | Individual editable children | No | Automatic context management. | Context and cost |
compaction.auto |
Boolean | true |
Yes | No | Compact when the context fills up. | Context and cost |
compaction.reserveTokens |
Integer | 16384 |
No | No | Keep this much context free for the response. | Context and cost |
compaction.keepRecentTokens |
Integer | 20000 |
No | No | Keep this much recent conversation verbatim during compaction. | Context and cost |
modelCatalog |
Object | Child defaults below | No | No | Model catalog refresh settings. | Models |
modelCatalog.enabled |
Boolean | true |
No | No | Refresh model windows and prices from the network; keep using the stored copy when off. | Privacy |
modelCatalog.url |
String | https://api.tatu.codes |
No | No | Base URL for catalog refreshes. | Privacy |
vision |
Object | None | Yes, as provider/model |
No | Choose a model to describe images when the session model takes none. | Images |
vision.provider |
String | None | Through /settings vision |
No | Provider of the image-description model; both vision fields must be set after merging files. | Images |
vision.model |
String | None | Through /settings vision |
No | ID of the image-description model. | Images |
subagents |
Object | Automatic tier models | Individual tiers | No | Configure the fast and balanced subagent tiers. |
Subagents |
subagents.fast |
Object; legacy model string accepted | Automatic | Through /settings subagents.fast |
No | Fast-tier model and effort. | Subagents |
subagents.fast.model |
String | Catalog’s fast model, then the session model | Through /settings subagents.fast |
No | Set a provider/model for the fast tier. |
Subagents |
subagents.fast.effort |
String | Inherit the session effort only when using its model; otherwise model default | Through /settings subagents.fast |
No | Set tier effort or default. |
Subagents |
subagents.balanced |
Object; legacy model string accepted | Automatic | Through /settings subagents.balanced |
No | Balanced-tier model and effort. | Subagents |
subagents.balanced.model |
String | Catalog’s balanced model, then the session model | Through /settings subagents.balanced |
No | Set a provider/model for the balanced tier. |
Subagents |
subagents.balanced.effort |
String | Inherit the session effort only when using its model; otherwise model default | Through /settings subagents.balanced |
No | Set tier effort or default. |
Subagents |
web |
Object | Child defaults below | Individual editable children | No | Services used by the web tools. | The web |
web.search |
Array of strings | ["firecrawl", "parallel", "exa", "llm"] |
No | No | Search services, in attempt order; a list replaces the lower-priority list. | The web |
web.fetch |
Array of strings | ["local", "jina", "firecrawl", "parallel", "exa", "llm"] |
No | No | Page-reading services, in attempt order. | The web |
web.otherProviders |
Boolean | false |
Yes | No | Let the llm web service use other signed-in providers and spend their quota. |
The web |
codemode |
Object | Child defaults below | No | No | The codemode tool, which runs a JavaScript program that calls other tools. |
Programs |
codemode.enabled |
Boolean | true |
No | No | Give the model the codemode tool; read at startup. |
Programs |
daemon |
Object | Child defaults below | Individual children | Yes | Project files cannot configure the daemon. | Daemon |
daemon.mode |
String | new-session |
Yes | Yes | Start on demand, with Tatu, or with Tatu and phone access: new-session, with-tatu, with-tatu-phone. |
Daemon |
daemon.root |
String | None; asked when first needed | Yes | Yes | Folder for new sessions; use an absolute path or a leading ~. |
Daemon |
hooks |
Object mapping events to matcher lists | None | No | No | Shell hooks for PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop; they run with your permissions, not per-tool permission gates. |
Hooks |