Open Settings with the gear at the right end of the title bar, with Cmd+,,
or from Tori > Settings… in the menu bar. The
rail on the left lists the panes; the search box at the top finds a setting by
name and badges each pane with how many rows match. The keyboard button in the
header opens the shortcut sheet.
Every row is also a Preferences: command in the palette (Cmd+K), which
opens Settings on that row, or flips it for an on and off setting.
Settings are saved in ~/.config/tori/settings.json. You can edit the file by
hand; Tori applies a change from either side the moment the file changes.
Editor rows can be overridden for one branch or worktree: select it in the
sidebar, then Set here on the row. The override is written to that
workspace’s .tori/settings.json, which Tori keeps out of git.
Agents
Card per adapter, not fixed fields: found or not, version against what Tori last measured, an on or off switch for whether it is offered, and per account usage controls. See Supported agents and adapters.
Chat
Sessions
| Setting | Default | Effect |
|---|---|---|
| Open sessions in | Chat | Which surface a sidebar session opens in by default |
| Stream responses | On | Listed, but has no effect yet |
| Transcript density | Comfortable | Listed, but has no effect yet |
| Tool output lines | 20 | Lines shown before a tool’s output folds; 0 shows all |
| Show every hook event | Off | Off shows only failing hooks; on shows every execution |
| Collapse agent work | Off | Folds thinking, tool calls, hooks and answered questions between two replies into a one line card |
| Answer the agent’s questions here | On | Structured questions render as an answerable form inline |
| Attach long pastes as files | On | A paste over 30 lines or 3000 characters becomes a file chip |
| Mark secret file reads | On | A turn that read a secret file, or ran a command naming one, says so in the chat, on its tab and in Checkpoints. See Secret watch |
| Mark edits made without reading | On | An ACP agent’s edit to a file the session never read, searched or named says so on the call and its turn. See Blind edits |
| Mark unverified turns | On | A turn that changed code says whether a test, type check, lint or build ran after its last edit: verified, failed, or unverified when nothing ran or its exit was not seen. See Verification |
| Watch branches for conflicts | On | A branch that would conflict with its base, or a file a session in another worktree is changing too, says so on its row, its tab, in Checkpoints and in the Inbox. Off runs none of these checks. See Conflict radar |
| Resume at reset | Off | A Claude chat stopped by a usage limit gets one message from Tori to continue, shortly after the limit resets |
Notifications
| Setting | Default | Effect |
|---|---|---|
| Notify when a session needs you | On | A notification when a session asks a question or wants a permission |
| Play a sound when a session needs you | Off | With a play button to hear it |
| Notify when a chat finishes its turn | Off | A notification at the end of every turn |
| Play a sound when a chat finishes its turn | Off | With a play button to hear it |
| Show the needs you count in the menu bar | On | The Dock badge’s number, beside Tori’s menu bar icon |
Safety
| Setting | Default | Effect |
|---|---|---|
| Snapshot on each prompt | On | One checkpoint per prompt, for diff and revert |
Read aloud
On an Intel Mac this group is one row, Voice model, saying Needs an Apple Silicon Mac.
| Setting | Default | Effect |
|---|---|---|
| Voice size | Not downloaded | Which voice model is installed: Smaller (107 MB) or Larger (340 MB), the natural voice with 28 voices, or Fastest (60 MB), which starts quickest with eight voices and sounds a little less natural. The row shows the installed one with Change, which opens the download dialog, and Delete, which asks first. While a download runs it shows the progress and Cancel. See Read a reply aloud |
| Pronunciation | Spelled out | A word Tori does not know is spelled out letter by letter. Install espeak-ng runs brew install espeak-ng in a dock terminal, and once it has, the row says espeak-ng says the words Tori does not know with Uninstall beside it. Without Homebrew the row only names espeak-ng. espeak-ng is not part of Tori, which is why it is a separate install |
| Voice | Heart, or Bella on Fastest | The voices of the installed model: 28 with Smaller or Larger, American English first and then British, eight with Fastest. A voice since removed falls back to the default. The play button, Hear this voice, reads a sample. With no model downloaded the row shows Download instead of the list |
| Speed | 1.0x | From 0.5x to 2x. The speed button on the reading chip changes this same setting. See Read a reply aloud |
Dictation
On an Intel Mac the row says Needs an Apple Silicon Mac.
| Setting | Default | Effect |
|---|---|---|
| Model | Not downloaded | Which speech to text model is installed for the composer’s dictation button: Moonshine (67 MB), small and quick, or Parakeet (661 MB), more accurate. While Parakeet is installed the row carries its credit, Parakeet by NVIDIA, CC BY 4.0. With none downloaded the row shows Download; with one it shows the model with Change, which opens the download dialog, and Delete, which asks first. While a download runs it shows the progress and Cancel. See Dictate a message |
Spending
| Setting | Default | Effect |
|---|---|---|
| Show what work costs | On | What a branch, a pull request and an autopilot item have cost, and a waiting item’s estimate. Off hides them; the limits below still apply (What work costs) |
| Warn above | 4 chats | Live chats at once before Tori warns; 0 turns it off |
| Stop this chat after | No limit | Dollar ceiling for one session |
| Stop this project after | No limit | Dollar ceiling summed across every chat in a project |
| Stop an autopilot item after | No limit | Dollar ceiling across every session the autopilot runs for one item; a project or item can set its own (What work costs) |
| Stop at context | No limit | Percentage of context window; recovers after compaction |
| Warn at | 80% | Fraction of a ceiling before Tori warns |
Autopilot
| Setting | Default | Effect |
|---|---|---|
| Enable autopilot | Off | Puts the Cockpit switch in the title bar |
| Autopilot model | Claude | Agent, account and model autopilot’s own session runs on |
| Worker stalled after | 20 min | Silent mid-turn time before a worker is flagged stalled |
| Compact at context | Agent decides | Percentage past which Tori sends /compact between the autopilot’s turns |
| Workers at once | 2 | How many workers run at a time, kept one under Warn above |
Editor
Behaviour (all workspace overridable)
| Setting | Default | Effect |
|---|---|---|
| Format on save | Off | Runs the file’s formatter before writing |
| Organize imports on save | Off | Sorts and drops unused imports before formatting |
| Fix all on save | Off | Applies every available fix before organizing and formatting |
| Trim trailing whitespace on save | Off | Strips trailing whitespace first |
| Insert final newline on save | Off | Ensures exactly one trailing newline |
| Code lens | Off | Shows reference and implementation counts above lines |
| Vim keybindings | Off | Modal editing |
Editing
| Setting | Default | Effect |
|---|---|---|
| Tab size | 2 | Indent width; .editorconfig outranks this |
| Indent with spaces | On | Off uses tab characters |
| Indentation guides | On | Vertical guides per indent level |
| Current line highlight | All | Where the caret’s line is marked |
| Soft wrap long lines | Off | Default for every buffer |
| Show spaces and tabs | Off | Renders whitespace glyphs |
| Scroll past the last line | On | Lets the last line reach the viewport top |
| Colour brackets by depth | Off | Nesting colours for brackets |
| Bracket pair guide lines | Off | Vertical connectors between a pair |
| Minimap | Off | Document overview strip |
| Sticky scroll | Off | Pins enclosing scope headers over the viewport |
| Word completion without a language server | On | Buffer word completion where no server claims the file |
| Keep unsaved edits across a quit | On | Stashes and restores unsaved buffers instead of prompting |
| Compact single-child folders | On | Collapses single-child folder chains in the file tree |
| Open Markdown and SVG rendered | Off | Opens those files in the rendered view instead of the source |
| Git blame | Off | Per-line blame in the gutter; an uncommitted line names the agent turn that wrote it |
| Side by side diffs | Off | Two column vs inline diff rendering |
| Send hunk comments right away | Off | Sends each hunk comment as you write it instead of holding it for one Send |
| TODO tags | TODO, FIXME, HACK, XXX | Tags the TODO panel searches for, workspace overridable |
Panes
| Setting | Default | Effect |
|---|---|---|
| Terminals open in | Leftmost | Which end of the split a new terminal, agent, command or task tab lands in |
| Chats open in | Leftmost | Same, for chat tabs |
| Files open in | Rightmost | Same, for opened files |
Sidebar
| Setting | Default | Effect |
|---|---|---|
| Space tiles | Bottom | Where the space strip sits: the bottom of the sidebar, or its left edge |
| Card colours | Subtle | Subtle draws every lane and group card neutral; Colourful tints lanes by state and groups by their own colour |
| Lanes for | Default | Which lane setup the rows below edit: Default, Home or a space. A space follows Default until changed; Reset to default gives it back |
| PR lanes | Off | Sorts each project’s branches into Working, In review, Reviewing and Done by pull request state |
| Own lanes | Changes requested, Approved, Review requested | The states that get a lane of their own, above the lane they come from |
| Fold into In review | Off | Shows Reviewing inside In review |
| Branch line | Full | The second line under a branch: Off, PR only or Full |
| Branch line items | All but Skipped checks | What Full shows: PR, Stack, Watched, Checks, Skipped checks, Diff size, Files, Spend, Age, Comments |
LSP, Debuggers, Linters, Formatters, Projects
Card grids, not fixed fields, one card per server, debugger, linter or formatter with an on or off switch and install controls where they apply. Projects lists which folders you have marked trusted, required for a server or debugger that runs project code. See Language tooling.
Projects also holds Unattended sessions: Never run unattended, the commands a session may not run while nobody is watching, and Allowed domains when boxed, where a boxed Claude session’s shell may connect. One entry per line, each with Reset to defaults. See When nobody is watching.
Appearance
| Setting | Default | Effect |
|---|---|---|
| Theme | Tori Dark | 22 bundled, in Dark and Light tabs. See Themes and fonts |
| Zoom | 1x | Scales chrome, editor and terminal together |
| UI font family / size | Inter, 15px | |
| Editor font family / size | SF Mono, 15px | |
| Terminal font family / size | JetBrains Mono Nerd Font, 15px | |
| Line height | 1.5 |
Integrations
Git
| Setting | Default | Effect |
|---|---|---|
| Git fetch every | 10 min | How often git fetch runs in the background; 0 turns it off. Pull request status and review requests refresh every 2 minutes either way |
| Show Topic worktrees in Spaces | Off | Also lists a Topic’s worktrees under their repository in Spaces |
| When a chat needs a worktree | Ask me first | What a Topic chat gets when it asks for a worktree in a repository it can only read: Ask me first, Create it or Refuse. See Chats in a Topic |
| Remove worktrees after merge | Off | Removes a clean worktree once its pull request merged, active Space only. See Remove worktrees automatically |
| Remove idle worktrees after | Off | Removes a clean, pushed worktree idle for 3, 7, 14 or 30 days. The branch is kept |
Hosts
Sign in to GitHub or GitLab accounts, per repo account picks, and whether a host’s account is also used for git push and fetch, for Tori only or for git everywhere. See Pull requests and issues.
| Setting | Default | Effect |
|---|---|---|
| Show pull requests and checks | On | Off stops polling the host while keeping your sign-in |
| Let a chat watch a pull request | Off | Lets a chat be woken with a pull request’s news; each wake is a paid turn |
Remote
| Setting | Default | Effect |
|---|---|---|
| Remote access | Off | Lets a paired phone reach Tori over Tailscale |
| Tailscale | Shows whether Tailscale is installed and connected | |
| Listen on | Not set | Your Tailscale address, or this Mac only |
| Port | 47821 |
See Pairing and remote access.
Browser
| Setting | Default | Effect |
|---|---|---|
| Browsers | Each browser Tori found, and whether its file is the one this version writes | |
| Install | Lets the browser extension reach Tori; installing again replaces its key | |
| Extension | Get the extension opens its Chrome Web Store page in your default browser | |
| Connected | Whether the extension has reached Tori since the last Install, or which side to update | |
| Revoke | Drops the extension’s connection; it needs Install again |
Advanced
Base folder: shown, and changeable, from here. Changing it does not move anything on disk, Tori just starts listing whatever is under the new folder. Sort projects… scans the base folder and opens Sort projects into spaces, for projects that are not in a space yet; see The grouping view. Forget base folder returns you to first run setup without deleting anything.
Crash logs: if Tori ever closes on its own, it writes a file under
~/.config/tori/crashes/ and says so on the next launch. This section lists
those files and the version you are running. Report a bug opens the bug
form in your browser, prefilled; nothing is sent anywhere without that
click.
Terminal command: Add writes one line to your shell profile
(~/.zprofile, or ~/.bash_profile if your login shell is bash) so a
terminal outside Tori can run tori, for tori attach or tori sessions.
New terminals pick it up. Remove takes that line out and nothing else.
Settings that live elsewhere
Some settings belong to one project, account or Topic, and are set where that thing is rather than in the Settings window.
| Setting | Where | Effect |
|---|---|---|
| Project icon | Project settings > General | Automatic, an image or a picked glyph |
| Setup command, and whether scripted sessions wait for it | Project settings > Worktrees, or Tooling for a repo | Runs in every new worktree |
| Run command | Project settings > Worktrees, or Tooling for a repo | Started and stopped by hand in a worktree |
| Teardown command | Project settings > Worktrees, or Tooling for a repo | Runs before a worktree is removed |
| Shared files | Project settings > Worktrees | Links untracked files into every worktree |
| Agents allowed in a project | Project settings > Agents | Limits agents and accounts |
| Remembered chat picks | Project settings > Agents | Shown per worktree, with Forget all |
| Second opinion reviewer | Project settings > Agents | A different agent from the session’s, or one fixed agent and account |
| Ports per worktree | Project settings > Tooling | How many of the block are exported |
| Verification commands | Project settings > Tooling | What counts as a check |
| Host account for a repository | Project settings > General | Which login its pull requests and pushes use, kept per remote |
| Autopilot contract | Project settings > Agents | How work ships and how far it goes |
| Usage windows, warn threshold, notify | Settings > Agents, per account | Which quota bars show and when they warn |
| Sandbox level | Project settings > Tooling | As me, boxed when unattended, or always boxed |
| Trusted projects | Project settings > Tooling, and Settings > Projects | Which folders may run their own code |
| Commit box, history tabs | Changes panel ... menu |
Shown or hidden |
| Follow live edits | Composer bar | Not remembered across a launch |
| Editor behaviour for one project | <project>/.tori/settings.json |
Overrides the workspace overridable rows above |
| More secret file patterns | secretWatch.patterns in ~/.config/tori/settings.json |
Adds to what Secret watch marks |
Every row of the Settings window is also a Preferences: command in the
palette, and the search box at the top of Settings badges each tab with how
many rows match as you type.