# Settings

> Every key in settings.toml, and what it does.

`~/.config/cydonia/settings.toml` is written with defaults on first run and read
on launch. Everything in it has a control in **Settings** (⌘,); editing the file
by hand is supported, and never required.

`state.toml` beside it is bookkeeping — which projects were open, where the
panels were left. Preferences worth carrying to another machine are in
`settings.toml`; the rest is not.

## Document keys

These come first in the file: a bare key written after a table would belong to
that table.

| Key | Default | What it is |
| --- | --- | --- |
| `watch_bounce` | — | How long a project's `.cydonia/` must go quiet before the watch re-reads it, in milliseconds |
| `auto_update` | `true` | Whether Cydonia looks for a new release on its own |
| `notify_turns` | `true` | Whether a turn finishing in the background is posted to the system |

`auto_update` switches the looking and the fetching, not the swap: a staged
release waits until a restart is asked for. Off is an app that reaches the
network for a version only when the menu item is picked.

`watch_bounce` is clamped on the way in — the ends of the range are what a hand
cannot reach past.

## `[appearance]`

| Key | Default | What it is |
| --- | --- | --- |
| `mode` | system | Light, dark, or whatever the OS is doing |
| `opaque` | unset | Hold the window opaque; unset leaves the frost to the appearance |
| `cursor_blink` | `true` | Off holds the caret lit |
| `text_size` | 13 | The body size the type ladder is scaled against, in points, clamped to 11–17 |
| `article_font_size` | unset | Unset keeps articles following the interface size |
| `mono_font_size` | 13 | Terminals, file source and previews, in points, clamped to 8–40; reads a pre-merge `terminal_font_size` |
| `ui_font` | unset | The family the interface is set in; unset is the system UI font |
| `article_font` | unset | The family articles and transcripts are set in; unset follows `ui_font` |
| `mono_font` | unset | The family terminals, code and file source are set in; unset is the system monospace face |
| `hue` | `0.0` | The greys' oklch hue, in degrees |
| `chroma` | `0.0` | How much of that hue they carry; zero is the shipped neutral |
| `wide_pages` | `false` | How wide a page with nothing of its own to say is set |
| `board_view` | `lanes` | How a new board is laid out; every board then carries its own answer |
| `indent_project_rows` | `true` | Indent sidebar items under project headings |
| `scrollbars` | `scrolling` | `scrolling`, `always` or `never` |
| `sidebar_scrollbars` | `never` | The same three |
| `wrap_code` | `false` | Whether a long line wraps inside a code block rather than scrolling |
| `highlight` | `yellow` | The colour behind `==text==` |
| `selection` | unset | The colour behind selected text; unset is the palette's |
| `search` | unset | The colour behind the current find match, the others at half strength; unset is the accent |
| `caret` | unset | The caret's colour; unset is the palette's |
| `caret_shape` | `bar` | `bar`, `block` or `underline` |
| `caret_height` | `line` | How tall a block caret stands: `line` for the line, `text` for the text |

A colour is a preset name — `red`, `orange`, `yellow`, `green`, `mint`, `teal`, `cyan`, `blue`, `indigo`, `purple`, `pink` or `brown`, each following light and dark — or `#rrggbb`. A value that is neither reads as that key's default.

A size out of range paints an interface nobody can read the settings window to
fix, so hand-edited sizes are clamped before layout sees them.

## `[features]`

```toml
[features]
sessions = false
boards = true
tables = false

[features.panel]
review = true
files = true
browser = true   # no effect on Linux
```

See [Features](https://cydonia.sh/docs/general/features.md).

## `[mcp]`

```toml
[mcp]
serve = true
write = false
delete = false
```

See [MCP](https://cydonia.sh/docs/agents/mcp.md).

## `[browser]`

| Key | Default | What it is |
| --- | --- | --- |
| `home` | `https://duckduckgo.com` | What a new tab opens on |
| `search` | DuckDuckGo | Where a search from the address field goes; `%s` is the query |
| `links` | `system` | Where a web link in an article or a transcript opens: `system` or `panel` |
| `agents_read` | `true` | Offer agents the browser tools that read pages |
| `agents_act` | `true` | Offer agents the browser tools that click and type; needs `agents_read` |
| `agents_blocked` | `[]` | Hosts agents may not read or act on, subdomains included |
| `keep_signed_in` | `true` | Keep cookies and storage across restarts; off builds each page in memory |

The browser tools are offered only while `[features.panel] browser` is on, and never on Linux. `agents_blocked` is checked against the tab's address when a call arrives.

## `[shortcuts]`

```toml
[shortcuts]
emacs = false
new_article = "cmd-shift-n"
activate = "alt-space"
```

`emacs = true` adds ⌥B/⌥F word movement and ⌥D word deletion. Every other key is
a command name and the chord it answers to. An unknown command name is kept, so
a file edited by hand is not rewritten under you. See [Keyboard](https://cydonia.sh/docs/reference/keyboard.md).

## `[[agents]]`

```toml
[[agents]]
name = "my-agent"
command = "path/to/agent"
args = ["--acp"]
# env = { KEY = "VALUE" }
```

See [Installing agents](https://cydonia.sh/docs/agents/install.md).