# The other tables

URL: https://tuios.dev/docs/configuration/other-tables

> The other tables: part of the Configuration of TUIOS.

This page is one part of `docs/CONFIGURATION.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/CONFIGURATION.md). The [Configuration](https://tuios.dev/docs/configuration) page lists every part.

## Keybindings: the `[keybindings]` table

### leader\_key

The prefix key. The default is `ctrl+b`.

```toml
[keybindings]
leader_key = "ctrl+a"
```

`alt+space` is already the app launcher.

`opt+` and `option+` mean `alt+` on every platform, `cmd+` and `command+` mean `super+`, and `control+` means `ctrl+`. See [Modifier spellings](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#modifier-spellings). Press the leader two times in terminal mode to send it to the pane.

If TUIOS cannot read the leader, the leader is `ctrl+b` until you correct it. See [When a key is wrong](https://tuios.dev/docs/configuration#when-a-key-is-wrong).

### lock

Lock mode gives every key in terminal mode to the pane, except the leader.

```toml
[keybindings]
lock = true
```

This option is in the [option reference](https://tuios.dev/docs/option-reference): [`keybindings.lock`](https://tuios.dev/docs/option-reference#keybindings.lock).

See [Lock mode](https://tuios.dev/docs/keybindings#lock-mode).

### nest\_exit\_key

The key that ends [nest mode](https://tuios.dev/docs/keybindings#nest-mode). The default is `"f12"`. A key tuios cannot read goes back to `"f12"`, and a key that programs type is reported as a problem.

### Keybinding sections

Each section is a table under `[keybindings]`. Each action takes a list of keys. The [Keybindings](https://tuios.dev/docs/keybindings) page lists every default.

| Section             | When it is active                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `window_management` | Window mode: windows, sessions, zoom, copy                                                                                                                                |
| `workspaces`        | Window mode: switch and move between workspaces                                                                                                                           |
| `layout`            | Window mode: snapping, tiling, swaps, resizes, splits, preselect                                                                                                          |
| `mode_control`      | Window mode: enter terminal mode, help, settings, quit                                                                                                                    |
| `restore_minimized` | Window mode: restore a minimized window by number                                                                                                                         |
| `system`            | Window mode: the spotlight                                                                                                                                                |
| `navigation`        | Empty. Kept so older files still parse                                                                                                                                    |
| `terminal_mode`     | Terminal mode, no prefix                                                                                                                                                  |
| `global`            | Both modes: the command palette and the launcher                                                                                                                          |
| `prefix_mode`       | After the leader key                                                                                                                                                      |
| `window_prefix`     | After leader, t                                                                                                                                                           |
| `minimize_prefix`   | After leader, m                                                                                                                                                           |
| `workspace_prefix`  | After leader, w                                                                                                                                                           |
| `layout_prefix`     | After leader, L                                                                                                                                                           |
| `tape_prefix`       | After leader, T                                                                                                                                                           |
| `debug_prefix`      | After leader, D                                                                                                                                                           |
| `script`            | While a tape plays                                                                                                                                                        |
| `sidebar`           | While the rail has the keyboard                                                                                                                                           |
| `sidebar_files`     | While the rail's cursor is on a file row. Checked before `sidebar`                                                                                                        |
| `sidebar_agents`    | While the rail's cursor is on an agent row. Checked before `sidebar`                                                                                                      |
| `inbox`             | While the Inbox is open                                                                                                                                                   |
| `inbox_peek`        | While a prompt is open over the Inbox                                                                                                                                     |
| `mail`              | While the mailbox is open                                                                                                                                                 |
| `lists`             | The cursor keys of every list: the palette, the launcher, the pickers, the menus and the settings page. See [List keys](https://tuios.dev/docs/keybindings#the-full-list) |
| `gui`               | Keys of the native GUI client. The terminal client does not read them                                                                                                     |

### Key syntax

- **Modifiers:** `ctrl+`, `alt+`, `shift+`, `super+`. Also `opt+` and `option+`, which mean `alt+`, `cmd+` and `command+`, which mean `super+`, and `control+`, which means `ctrl+`. These spellings work on every platform.
- **Special keys:** `enter`, `return`, `esc`, `escape`, `tab`, `space`, `backspace`, `delete`, `up`, `down`, `left`, `right`, `home`, `end`, `pgup`, `pageup`, `pgdown`, `pagedown`, `f1` to `f12`.
- **Any single character:** letters, digits, symbols, and accented letters.
- **Held modifiers:** `leftalt`, `rightalt`, `leftctrl`, `leftsuper` and the like, for `hold_window_mode` only. They need the Kitty keyboard protocol.

`super+` only reaches TUIOS in terminals that speak the Kitty keyboard protocol. On Linux, `opt+1` is `alt+1`. See [One config on macOS and Linux](https://tuios.dev/docs/configuration/files-input-and-focus#one-config-on-macos-and-linux).

```toml
[keybindings.window_management]
new_window = ["n", "ctrl+t"]   # several keys for one action
close_window = []              # no key: the key goes to the pane
```

An empty list is different from a missing line. A missing action gets its default back at the next load. An empty list stays empty.

`shift+1` and `!` are the same key, and so are `shift+a` and `A`. Binding one spelling binds both. Do not bind the two spellings to different actions.

### Platform defaults

On macOS, the workspace and preselect defaults use `opt+`, and `terminal_mode` adds `opt+tab`, `opt+shift+tab` and `opt+esc`. Writing `alt+` on macOS works but gives an advisory warning. Elsewhere the defaults use `alt+`. See [Keybindings](https://tuios.dev/docs/keybindings).

## The `[daemon]` table

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`daemon.agent_binaries`](https://tuios.dev/docs/option-reference#daemon.agent_binaries), [`daemon.single_client`](https://tuios.dev/docs/option-reference#daemon.single_client), [`daemon.ssh_agent`](https://tuios.dev/docs/option-reference#daemon.ssh_agent), [`daemon.display`](https://tuios.dev/docs/option-reference#daemon.display), [`daemon.respond_from_shell`](https://tuios.dev/docs/option-reference#daemon.respond_from_shell).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`daemon.log_level`](https://tuios.dev/docs/option-reference#daemon.log_level), [`daemon.agent_autodetect`](https://tuios.dev/docs/option-reference#daemon.agent_autodetect), [`daemon.agent_detect_seconds`](https://tuios.dev/docs/option-reference#daemon.agent_detect_seconds), [`daemon.agent_stall_seconds`](https://tuios.dev/docs/option-reference#daemon.agent_stall_seconds), [`daemon.subagent_fade_seconds`](https://tuios.dev/docs/option-reference#daemon.subagent_fade_seconds), [`daemon.resume_agents`](https://tuios.dev/docs/option-reference#daemon.resume_agents), [`daemon.persist_scrollback`](https://tuios.dev/docs/option-reference#daemon.persist_scrollback), [`daemon.persist_scrollback_lines`](https://tuios.dev/docs/option-reference#daemon.persist_scrollback_lines), [`daemon.persist_scrollback_kb`](https://tuios.dev/docs/option-reference#daemon.persist_scrollback_kb), [`daemon.keep_awake`](https://tuios.dev/docs/option-reference#daemon.keep_awake), [`daemon.window_size`](https://tuios.dev/docs/option-reference#daemon.window_size), [`daemon.client_follows_upgrade`](https://tuios.dev/docs/option-reference#daemon.client_follows_upgrade).

A change to `single_client`, `ssh_agent` or `display` in the file applies to the next attach.

### Daemon timings

The daemon's timings are whole seconds in `[daemon]`, and `0` reads as the default. The daemon reads them when it starts. Each has an environment variable, read at the same time, that wins over the file:

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`daemon.agent_detect_seconds`](https://tuios.dev/docs/option-reference#daemon.agent_detect_seconds), [`daemon.agent_stall_seconds`](https://tuios.dev/docs/option-reference#daemon.agent_stall_seconds), [`daemon.subagent_fade_seconds`](https://tuios.dev/docs/option-reference#daemon.subagent_fade_seconds), [`daemon.cleanup_seconds`](https://tuios.dev/docs/option-reference#daemon.cleanup_seconds), [`daemon.pr_poll_seconds`](https://tuios.dev/docs/option-reference#daemon.pr_poll_seconds), [`daemon.transfer_keep_seconds`](https://tuios.dev/docs/option-reference#daemon.transfer_keep_seconds), [`daemon.dispatch_ready_seconds`](https://tuios.dev/docs/option-reference#daemon.dispatch_ready_seconds).

`agent_autodetect` reads `TUIOS_AGENT_AUTODETECT` the same way: `false`, `no`, `off` or `0` turns detection off.

These timings and limits have no environment variable. `0` reads as the default, and a value outside the range moves to the nearer end.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`daemon.save_seconds`](https://tuios.dev/docs/option-reference#daemon.save_seconds), [`daemon.exec_timeout_seconds`](https://tuios.dev/docs/option-reference#daemon.exec_timeout_seconds), [`daemon.reconnect_seconds`](https://tuios.dev/docs/option-reference#daemon.reconnect_seconds), [`daemon.host_heartbeat_seconds`](https://tuios.dev/docs/option-reference#daemon.host_heartbeat_seconds), [`daemon.host_heartbeat_timeout_seconds`](https://tuios.dev/docs/option-reference#daemon.host_heartbeat_timeout_seconds), [`daemon.host_call_timeout_seconds`](https://tuios.dev/docs/option-reference#daemon.host_call_timeout_seconds), [`agents.ask_wait_seconds`](https://tuios.dev/docs/option-reference#agents.ask_wait_seconds), [`agents.undo_window_seconds`](https://tuios.dev/docs/option-reference#agents.undo_window_seconds), [`files.drop_keep_hours`](https://tuios.dev/docs/option-reference#files.drop_keep_hours), [`files.drop_keep_mb`](https://tuios.dev/docs/option-reference#files.drop_keep_mb).

The daemon reads them when it starts. The client reads `reconnect_seconds` and `undo_window_seconds` from its own config, and a change applies at once. The time a dial to one machine may take is `connect_timeout` in that machine's `[hosts.NAME]` table.

### The display of the client

A daemon that a host link starts over ssh has no `WAYLAND_DISPLAY` or `DISPLAY`. Its panes have none either, so `wl-copy`, `wl-paste`, `xclip` and image paste fail. With `display = "follow"`, the default, the new panes of such a daemon get the display of the local client that attached to the session or used it last.

```toml
[daemon]
display = "follow"
```

- A daemon that has a `WAYLAND_DISPLAY` or a `DISPLAY` of its own keeps it. The option does nothing then.
- Each session has a link to the Wayland socket of the client: `wayland-<session id>.sock`, in the folder of the daemon socket. A new pane gets `WAYLAND_DISPLAY` set to the full path of the link. The link moves to the socket of the newest client.
- A new pane also gets `DISPLAY` and `XAUTHORITY` of the client. `DISPLAY` is a name, not a path, so a pane keeps the value it started with.
- A shell that started before a desktop client attached has no display. Run `eval "$(tuios display-env 2>/dev/null)"` in that shell, or add the line to your shell rc. See [`tuios display-env`](https://tuios.dev/docs/cli-reference/daemon-mode#tuios-display-env).
- When the client detaches, the session uses the display of the client before it. When no attached client has a display, tuios removes the link, and new panes get no display.
- tuios uses the display of `tuios attach` and `tuios new` only. The client must run on this machine, as your user, and outside every pane. tuios ignores a client that comes through a host link, a client of the tuios SSH server and a client of `tuios-web`.
- A `WAYLAND_DISPLAY` name such as `wayland-1` is looked up in the `XDG_RUNTIME_DIR` of the client, then in the one of the daemon, then in `/run/user/<uid>`. The client does not need `XDG_RUNTIME_DIR`.
- The Wayland socket must be a Unix socket that you own. `DISPLAY` must be `:N` or `:N.S`, and tuios ignores a forwarded display such as `localhost:10.0`. `XAUTHORITY` must be a file that you own.
- The option is read from the file only. `tuios set-config` cannot change it.

To change `window_size` for one session while it runs, use `tuios set-config daemon.window_size smallest -s NAME`. That value is not saved to the file. A change in the file applies when the daemon starts again.

`tuios set-config daemon.log_level messages` changes the level of a running daemon at once. `verbose` and `trace` also log pane content, window titles and paths. `tuios logs` reads the log.

## The `[startup]` table

`[startup]` decides how a new session starts. It never changes a running session.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`startup.daemon`](https://tuios.dev/docs/option-reference#startup.daemon), [`startup.tiled`](https://tuios.dev/docs/option-reference#startup.tiled), [`startup.layout`](https://tuios.dev/docs/option-reference#startup.layout), [`startup.open_default_window`](https://tuios.dev/docs/option-reference#startup.open_default_window), [`startup.start_in_terminal_mode`](https://tuios.dev/docs/option-reference#startup.start_in_terminal_mode), [`startup.session`](https://tuios.dev/docs/option-reference#startup.session), [`startup.window`](https://tuios.dev/docs/option-reference#startup.window).

When the file sets `layout` but not `tiled = true`, new sessions float and do not use the layout. TUIOS says so in the log viewer (Ctrl+B D l) and in `tuios config apply`: `[startup] layout is set, but [startup] tiled is off, so new sessions float and do not use the layout. Set tiled = true to use the layout.`

`session` and `window` change a plain `tuios` only. Other commands use the session you give them. `session` uses the daemon even when `daemon` is `false`.

`--standalone` and `TUIOS_NO_DAEMON=1` override `daemon` for one run or one shell. If the daemon will not start, a bare `tuios` runs standalone and says so.

> **Older config files keep their behaviour.** `daemon` and `tiled` default to `true` in a new install. A config file that already exists and does not mention them reads them as `false`, so an upgrade keeps the floating, standalone start it had. Add the keys to opt in.
>
> In the same way, v0.8.0 changed eight appearance defaults: the rail is on, on the right, 24 columns wide; the dock and the window titles are on top; a zoomed pane takes 95% of the screen; a double click starts typing; and the scrollbar is a track. A config file that sets one of these keys keeps its value. The first-run file older releases wrote names most of them, so such an install keeps the old look until you remove those lines.

A session keeps its own layout once it is running. Attaching never rearranges a session to match your config.

## The `[workspaces]` table

When the last pane on the workspace on screen closes, TUIOS shows the workspace you came from. This happens when the pane's program stops, when you close the pane, when `tuios xpanes -ss` closes it, and with `tuios close-workspace`.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`workspaces.return_when_empty`](https://tuios.dev/docs/option-reference#workspaces.return_when_empty), [`workspaces.new_window_when_empty`](https://tuios.dev/docs/option-reference#workspaces.new_window_when_empty).

TUIOS goes back in this order:

1. For a workspace that `tuios xpanes` opened, the workspace where you ran `tuios xpanes`.
2. The workspace you showed last that still has panes. After a chain of empty workspaces, TUIOS goes back past each one.
3. The workspace with the lowest number that has panes.

When no workspace has panes, TUIOS shows the splash screen. The workspace on screen is the same for every client of the session, so every client goes back. A pane that moves to another workspace does not close, so TUIOS does not go back.

```toml
[workspaces]
return_when_empty = false
```

The daemon reads the setting when it starts and when the file changes. `tuios set-config workspaces.return_when_empty false` changes it while TUIOS runs.

### A pane on an empty workspace

By default, a workspace with no panes shows the splash screen. To open a pane there when you switch to it, as tabs do in other multiplexers, turn on `new_window_when_empty`:

```toml
[workspaces]
new_window_when_empty = true
```

The new pane starts in the folder of the pane that had focus on the workspace you came from. It starts in the session's start folder (the folder that `tuios new --cwd` gave) when you came from a workspace with no pane, from a scratch terminal, or from a pane on another machine. With `appearance.new_window_follow_ssh = true`, a pane that runs ssh gives a new pane that runs the same ssh, as the new-window key does.

A pane opens only when you switch: with a workspace key, a click on the dock, go-to, the pane navigator or the command palette. These switches do not open a pane:

- `move_and_follow` and other moves that take a pane with them.
- `tuios xpanes`, `tuios select-workspace`, `tuios run-command` and tape scripts.
- The switch back that `return_when_empty` makes.
- The start of TUIOS and an attach to a session.

A workspace gets one pane, also when two clients switch to it at the same time. When you switch away before the pane opens, you stay where you went.

Each client reads the setting from its config file, and a change applies at once. The settings page lists it under Daemon, and `tuios set-config workspaces.new_window_when_empty true` changes it while TUIOS runs.

The daemon must be from the same release or newer. An older daemon opens no pane. Run `tuios restart-server` to load the new daemon.

## The `[launcher]` table

The app launcher starts a desktop entry in a new pane. A graphical program opens its own window, so its pane stays empty. Set [`launcher.gui_command`](https://tuios.dev/docs/option-reference#launcher.gui_command) to start such an entry with another command. The launcher adds the entry's argv to that command. Entries with `Terminal=true` and programs from `$PATH` still open in a pane.

```toml
[launcher]
gui_command = "tuios-wayland launch --"   # or "niri msg action spawn --"
```

> **Use a command that runs an argv.** Do not use a command that joins its arguments into a shell line, such as `swaymsg exec --` or `hyprctl dispatch exec`. With such a command, the text of a desktop entry becomes shell code. Any installed package can write a desktop entry.

[`launcher.keep_open`](https://tuios.dev/docs/option-reference#launcher.keep_open) keeps the pane of a launched program open after it exits. A line under the output shows the exit status. The option needs a daemon session.

```toml
[launcher]
keep_open = true
```

## The `[tape]` table

`[tape]` controls project tapes: a `.tuios.tape` file in a directory. See [Tape Scripting](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/TAPE_SCRIPTING.md).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`tape.autorun`](https://tuios.dev/docs/option-reference#tape.autorun), [`tape.auto_review`](https://tuios.dev/docs/option-reference#tape.auto_review).

A tape edited after you trusted it is untrusted again.

## The `[debug]` table

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`debug.show_key_events`](https://tuios.dev/docs/option-reference#debug.show_key_events).

`--show-keys` and Ctrl+B D k toggle the same overlay. See [Showkeys](https://tuios.dev/docs/showkeys).

## The `[screenshot]` table

`[screenshot]` sets the defaults for [`tuios screenshot`](https://tuios.dev/docs/cli-reference/inspection-commands#tuios-screenshot) and the in-app capture (Ctrl+B C). Each key has a command flag that overrides it for one capture.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`screenshot.format`](https://tuios.dev/docs/option-reference#screenshot.format), [`screenshot.directory`](https://tuios.dev/docs/option-reference#screenshot.directory), [`screenshot.copy`](https://tuios.dev/docs/option-reference#screenshot.copy), [`screenshot.preview`](https://tuios.dev/docs/option-reference#screenshot.preview), [`screenshot.frame`](https://tuios.dev/docs/option-reference#screenshot.frame), [`screenshot.background`](https://tuios.dev/docs/option-reference#screenshot.background), [`screenshot.padding`](https://tuios.dev/docs/option-reference#screenshot.padding), [`screenshot.radius`](https://tuios.dev/docs/option-reference#screenshot.radius), [`screenshot.shadow`](https://tuios.dev/docs/option-reference#screenshot.shadow), [`screenshot.controls`](https://tuios.dev/docs/option-reference#screenshot.controls), [`screenshot.title_format`](https://tuios.dev/docs/option-reference#screenshot.title_format), [`screenshot.font_family`](https://tuios.dev/docs/option-reference#screenshot.font_family), [`screenshot.font_file`](https://tuios.dev/docs/option-reference#screenshot.font_file), [`screenshot.scale`](https://tuios.dev/docs/option-reference#screenshot.scale), [`screenshot.cursor`](https://tuios.dev/docs/option-reference#screenshot.cursor).

```toml
[screenshot]
format = "svg"
frame = "plain"
background = "none"
padding = 24
```

`png` and `svg` carry the frame. `ansi` and `txt` are plain output, so the frame keys do not apply.

## The `[screensaver]` table

`[screensaver]` animates the screen after a period with no input. It is off by default.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`screensaver.enabled`](https://tuios.dev/docs/option-reference#screensaver.enabled), [`screensaver.idle_minutes`](https://tuios.dev/docs/option-reference#screensaver.idle_minutes), [`screensaver.effect`](https://tuios.dev/docs/option-reference#screensaver.effect), [`screensaver.while_busy`](https://tuios.dev/docs/option-reference#screensaver.while_busy).

```toml
[screensaver]
enabled = true
idle_minutes = 5
effect = "matrix"
```

There are 36 effects. `tuios list-options screensaver.effect` prints them. A plugin can add a saver: set `effect = "plugin/ID/SAVER"`. See [A screen saver in a plugin](https://tuios.dev/docs/plugins#a-screen-saver-in-a-plugin). The settings page previews each effect on your current screen.

S in window mode starts the screen saver now, whatever `enabled` says.

## The `[hints]` table

`[hints]` sets what [hints mode](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HINTS.md) (Ctrl+B F) labels.

This option is in the [option reference](https://tuios.dev/docs/option-reference): [`hints.patterns`](https://tuios.dev/docs/option-reference#hints.patterns).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`hints.builtins`](https://tuios.dev/docs/option-reference#hints.builtins), [`hints.alphabet`](https://tuios.dev/docs/option-reference#hints.alphabet), [`hints.open`](https://tuios.dev/docs/option-reference#hints.open), [`hints.dim`](https://tuios.dev/docs/option-reference#hints.dim), [`hints.all_panes`](https://tuios.dev/docs/option-reference#hints.all_panes).

See [What hints mode finds](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HINTS.md#what-hints-mode-finds) for the pattern names.

## The `[panes]` table

`[panes]` sets the keys of the [pane labels](https://tuios.dev/docs/find-a-pane#pane-labels) (Ctrl+B Q) and the first layout of the pane navigator (Ctrl+B /).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`panes.label_keys`](https://tuios.dev/docs/option-reference#panes.label_keys), [`panes.navigator_layout`](https://tuios.dev/docs/option-reference#panes.navigator_layout), [`panes.navigator_search`](https://tuios.dev/docs/option-reference#panes.navigator_search), [`panes.drag_and_drop`](https://tuios.dev/docs/option-reference#panes.drag_and_drop), [`panes.drag_and_drop_desktop`](https://tuios.dev/docs/option-reference#panes.drag_and_drop_desktop).

With `drag_and_drop` on, a program that speaks the protocol, such as yazi 26.9 or later, can drag files from its pane. Hold the left button on a file in terminal mode, and carry it to another pane. A pane whose program speaks the protocol takes the drop itself. Any other pane gets the paths as a paste, quoted for its shell, by the rules of [a drag from the rail](https://tuios.dev/docs/session-rail#drag-a-file-into-a-pane). tuios reads no file, and refuses a drop back into the pane the drag came from. The switch is off because the protocol is still settling.

### Drag and drop with the desktop

Set `drag_and_drop_desktop = true` with `drag_and_drop = true` to drag files between the desktop and the panes. The terminal that tuios runs in must speak the same protocol. Today that is kitty 0.47 or later. tuios asks the terminal once at startup.

```toml
[panes]
drag_and_drop = true
drag_and_drop_desktop = true
```

- **From the desktop**: drag a file from a file manager or a browser onto the tuios window. It lands on the pane under the pointer. A program that speaks the protocol takes it. Any other pane gets the path as a paste, by the rules above.
- **To the desktop**: a file that a program in a pane drags, such as yazi, becomes a drag on the desktop. Drop it on any other window. The desktop shows the file names and the pane they come from.
- tuios takes a drag only when the press went to a pane that offers drags. You still move a pane, select text and drag a row of the rail as before.
- The bridge is for a terminal on this machine. A client over SSH, through tuios-web, or attached to the daemon of another machine does not use it.
- Both switches apply without a restart.

## The `[path_picker]` table

`[path_picker]` sets `show_hidden`. With `true`, the [path picker](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#pick-a-path) shows the names that start with a dot when it opens. The default is `false`.

## The `[worktree]` table

`[worktree] path` sets where `tuios worktree new`, **New worktree...** on the rail and `tuios fan` put a worktree. The value is a path template. Empty is the default. See [Where a worktree goes](https://tuios.dev/docs/worktrees#where-a-worktree-goes).

```toml
[worktree]
path = "{{ repo_path }}/.worktrees/{{ branch | slug }}"
```

## The `[review]` table

`[review]` sets how a [review](https://tuios.dev/docs/agent-inbox#reviewing-an-agents-changes) opens.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`review.focus`](https://tuios.dev/docs/option-reference#review.focus), [`review.scope`](https://tuios.dev/docs/option-reference#review.scope).

```toml
[review]
focus = "files"
scope = "uncommitted"
```

`base` shows the changes since the base. In a plain repository, the base is the merge base with the upstream branch, so commits that you did not push yet are part of the review. `uncommitted` shows only the changes that are not committed. In the review, u still switches between the two, and b still sets another base. The compare view of two attempts does not use `scope`.

Both keys are on the settings page, in the Behavior section. `tuios set-config review.scope uncommitted` applies from the next review. tuios reads another value as the default and shows a warning when the config loads. `tuios set-config` refuses it.

## The `[tasks]` table

`[tasks]` sets how the [task board](https://tuios.dev/docs/task-boards) works.

This option is in the [option reference](https://tuios.dev/docs/option-reference): [`tasks.stages`](https://tuios.dev/docs/option-reference#tasks.stages).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`tasks.auto_stage`](https://tuios.dev/docs/option-reference#tasks.auto_stage), [`tasks.attachment_max_mib`](https://tuios.dev/docs/option-reference#tasks.attachment_max_mib), [`tasks.attachments_per_card`](https://tuios.dev/docs/option-reference#tasks.attachments_per_card), [`tasks.attachment_session_mib`](https://tuios.dev/docs/option-reference#tasks.attachment_session_mib), [`tasks.machine_cap`](https://tuios.dev/docs/option-reference#tasks.machine_cap).

```toml
[tasks]
stages = ["todo", "doing", "verify"]
auto_stage = false
machine_cap = 4
attachment_max_mib = 4
attachments_per_card = 10
```

A file over a limit is refused with an error that names the option. See [Attachments](https://tuios.dev/docs/task-boards#attachments).

The dispatch settings (mode, preset, caps, quiet hours, verify) are not in the config file. `tuios task dispatch` sets them, and the daemon saves them. See [Dispatch](https://tuios.dev/docs/task-boards#dispatch).

## The `[files]` table

`[files]` sets the copies that o on a file of another machine makes here, in the rail's files section.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`files.open_copy_ask_mb`](https://tuios.dev/docs/option-reference#files.open_copy_ask_mb), [`files.open_copy_max_mb`](https://tuios.dev/docs/option-reference#files.open_copy_max_mb), [`files.open_copy_keep_days`](https://tuios.dev/docs/option-reference#files.open_copy_keep_days).

## Shell prompt marks: the `[shell]` table

TUIOS turns on OSC 133 prompt marks in the bash and zsh shells it starts in panes, as Ghostty and kitty do. The marks say where a prompt starts, where a command starts, and how it ended. `tuios run`, `wait-for command-finished`, `capture-pane --last-command`, the scrollback browser and copy mode read them. A pane with marks also keeps one copy of its prompt when you make the pane narrower.

TUIOS does not change your files:

- **zsh** starts with `ZDOTDIR` set to a folder of TUIOS's own. Its `.zshenv` sets `ZDOTDIR` back to your value, reads your `.zshenv`, and adds the marks. zsh then reads your `.zprofile`, `.zshrc` and `.zlogin` as usual.
- **bash** starts with `--rcfile` set to a file that reads your `~/.bashrc` and then adds the marks. Your `PS1`, `PROMPT_COMMAND`, traps and `set -e` stay as they are. This needs bash 4.4 or newer.
- **fish 4** and **nushell** send the marks themselves, so TUIOS adds nothing. Other shells start as they are.

When your own prompt already sends a mark, TUIOS does not send that mark again. A shell starts less than 1 ms slower. To turn it off:

```toml
[shell]
integration = "off"   # default: "auto"
```

The change applies to new panes. `tuios new-window --shell-integration off` chooses for one pane, and `tuios doctor shell` shows which panes send marks. A pane that runs `ssh`, or a window on another machine, gets no marks from TUIOS: add the lines `tuios doctor shell` prints to the rc file there.

## The `[scratch]` table

`[scratch]` sets the size of the scratch terminal that Ctrl+B g shows in a popup. See [Scratch terminal](https://tuios.dev/docs/sessions#scratch-terminal).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`scratch.width`](https://tuios.dev/docs/option-reference#scratch.width), [`scratch.height`](https://tuios.dev/docs/option-reference#scratch.height).

The old `session` key is no longer used. TUIOS ignores it, and the config warnings tell you to remove it.

## The `[pip]` table

`[pip]` sets the size and the first corner of the picture-in-picture view. See [Picture in picture](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#picture-in-picture).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`pip.width`](https://tuios.dev/docs/option-reference#pip.width), [`pip.height`](https://tuios.dev/docs/option-reference#pip.height), [`pip.corner`](https://tuios.dev/docs/option-reference#pip.corner).

## The `[paste_buffers]` table

`[paste_buffers]` sets how many [paste buffers](https://tuios.dev/docs/paste-buffers) the daemon keeps. The daemon reads it when it starts and when the file changes.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`paste_buffers.limit`](https://tuios.dev/docs/option-reference#paste_buffers.limit), [`paste_buffers.max_kb`](https://tuios.dev/docs/option-reference#paste_buffers.max_kb).

A smaller limit removes the oldest buffers at once. A yank larger than `max_kb` does not become a buffer, but it still goes to the clipboard.

## Command keys

`[[keybindings.command]]` binds a key to a command that you write: a scratch terminal, a popup, a pane or a command with no window. A mistake in an entry is a warning, and TUIOS ignores that entry. See [Command keys](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#command-keys).

## Actions and menus of your own: the `[[actions]]` and `[menus]` tables

`[[actions]]` declares an action of your own, `user:NAME`: a built-in action, a program with its arguments (placeholders such as `{pane.cwd}` fill one argument each, and no shell reads them), or a plugin action. A key, a menu row or `tuios actions run` runs it. See [Your actions](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#your-actions).

`[menus.NAME]` declares a menu: a title and a list of rows, each an action or a submenu with an optional `key`, `label` and `when`. `open_menu:NAME` opens it, as a which-key panel from a key and in place from a right-click menu. The target names (`pane`, `session`, `file` and the others) are the shipped right-click menus: `add` puts rows after the row `after` names, `remove` takes rows out, and `items` replaces them. An action's `targets` and `when` decide where its row shows. See [Your menus](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#your-menus).

## The `[spotlight]` table

`[spotlight]` lights one part of the screen and dims the rest, for screen sharing. B in window mode, or Ctrl+B B in any mode, turns it on and off. While it is on, Esc in window mode or a click on the Spotlight chip in the dock turns it off. See [Spotlight](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#spotlight).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`spotlight.enabled`](https://tuios.dev/docs/option-reference#spotlight.enabled), [`spotlight.follow`](https://tuios.dev/docs/option-reference#spotlight.follow), [`spotlight.radius`](https://tuios.dev/docs/option-reference#spotlight.radius), [`spotlight.dim`](https://tuios.dev/docs/option-reference#spotlight.dim), [`spotlight.edge`](https://tuios.dev/docs/option-reference#spotlight.edge), [`spotlight.shake`](https://tuios.dev/docs/option-reference#spotlight.shake).

`follow = "cursor"` sends fewer bytes to a remote client.

## The `[dock]` table

`[dock]` sets what the bar draws: three ordered lists of component names, plus a table for each component that needs one. Edit it in the file, or with the **Dock > Components** editor on the settings page. `set-config` cannot change the lists.

```toml
[dock]
left   = ["mode", "workspaces", "trail", "tape"]
center = ["windows"]
right  = ["transfers", "notifications", "copy-help", "cpu", "ram", "clock", "session-controls"]

[dock.clock]
format = "15:04"

[dock.custom.branch]
command  = "git branch --show-current"
refresh  = "event:after-focus-change"
on-click = "tuios new-window log -- git log --oneline -20"
```

These lists are the default. A missing list uses the default. An empty list (`left = []`) draws nothing on that side.

The built-in components are `mode`, `workspaces`, `trail`, `tape`, `windows`, `transfers`, `notifications`, `copy-help`, `cpu`, `ram`, `clock`, `session-controls` and `session`. Listing one lets it draw. It still needs its own condition, so `cpu` still needs `show_cpu`. `copy-help` shows the keys of copy mode, multi copy mode and hints mode while the mode is open. See [Mode keys in the dock](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#mode-keys-in-the-dock).

`session-controls` shows an agents button when the session has an agent pane. The button opens the agents view, the same as `Ctrl+B i`. When agents wait for you, the button shows how many in the attention colour.

`transfers` shows the copies between machines. It shows nothing while no copy exists. One copy is a bar and a percent, `[####--] 61%`. More copies are a count and a percent, `3 copies 42%`. `waiting` means a link is down. `1 failed` stays until you open the Copies panel. A click opens the [Copies panel](https://tuios.dev/docs/keybindings/copy-mode#copies-between-machines).

`[dock.clock]` takes `format`, a Go time layout. A layout without seconds refreshes once a minute. `session` shows the session name, the workspace and the pane, such as `main 2:1`. It is in no default list. `[dock.session]` takes `format`, with `{session}`, `{workspace}` and `{pane}`. It also takes the cell style keys `fg`, `bg`, `bold`, `cap_left` and `cap_right`. `[dock.custom.NAME]` takes the same style keys. Colours are `#rrggbb`. When the `center` list has a clock or a custom cell, the centre is at the middle of the terminal. A notification does not move it, and it does not shorten the minimized pane labels. On a crowded bar, the centre moves left to keep the cells on the right on the screen. Click a cut notification to read the full message.

### Custom components

`[dock.custom.NAME]` defines a cell. Put `custom/NAME` in a list to place it.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`dock.custom.NAME.command`](https://tuios.dev/docs/option-reference#dock.custom.NAME.command), [`dock.custom.NAME.refresh`](https://tuios.dev/docs/option-reference#dock.custom.NAME.refresh), [`dock.custom.NAME.on-click`](https://tuios.dev/docs/option-reference#dock.custom.NAME.on-click), [`dock.custom.NAME.max-width`](https://tuios.dev/docs/option-reference#dock.custom.NAME.max-width), [`dock.custom.NAME.fg`](https://tuios.dev/docs/option-reference#dock.custom.NAME.fg), [`dock.custom.NAME.bg`](https://tuios.dev/docs/option-reference#dock.custom.NAME.bg), [`dock.custom.NAME.bold`](https://tuios.dev/docs/option-reference#dock.custom.NAME.bold), [`dock.custom.NAME.cap_left`](https://tuios.dev/docs/option-reference#dock.custom.NAME.cap_left), [`dock.custom.NAME.cap_right`](https://tuios.dev/docs/option-reference#dock.custom.NAME.cap_right).

With `push`, the command keeps running and each line it prints replaces the cell. With `event:`, the command runs again when the daemon reports one of those [hook events](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HOOKS.md).

A component whose command fails is hidden. `tuios list-dock-components` shows what each component last did and why a cell is missing. `tuios refresh-dock [name]` runs a component again now.

A command runs in the client, with a three second timeout. TUIOS reads at most 64 KiB of its output and stops the command when it prints more. SGR colour stays. TUIOS removes other control sequences, C1 controls, bidirectional and invisible characters, and bytes that are not UTF-8. Wide characters and emoji stay.

## SSH server limits: the `[ssh]` table

The `[ssh]` table sets the limits of the `tuios ssh` server. The server reads it when it starts. The defaults do not stop a normal login.

```toml
[ssh]
handshake_timeout = "120s" # time to finish the login; 0 turns the limit off
idle_timeout = "0"         # close a connection with no traffic for this long; 0 is off
max_handshakes = 32        # connections that log in at the same time; 0 is no limit
max_sessions = 64          # sessions open at the same time; 0 is no limit
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`ssh.handshake_timeout`](https://tuios.dev/docs/option-reference#ssh.handshake_timeout), [`ssh.idle_timeout`](https://tuios.dev/docs/option-reference#ssh.idle_timeout), [`ssh.max_handshakes`](https://tuios.dev/docs/option-reference#ssh.max_handshakes), [`ssh.max_sessions`](https://tuios.dev/docs/option-reference#ssh.max_sessions).

A duration is a value such as `90s`, `30m` or `2h`. A value that does not parse, or a negative value, gives a warning and the default. `tuios ssh --handshake-timeout`, `--idle-timeout`, `--max-handshakes` and `--max-sessions` replace these values for one run. The server writes the limits it uses to its log when it starts. `tuios set-config` cannot change this table.

## The `[hosts]` table

`[hosts]` names the other machines this daemon links to. Each host is a table.

```toml
[hosts.build]
addr = "gaurav@buildbox"

[hosts.work]
addr = "workstation"
connect_timeout = 5
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`hosts.NAME.addr`](https://tuios.dev/docs/option-reference#hosts.NAME.addr), [`hosts.NAME.connect_timeout`](https://tuios.dev/docs/option-reference#hosts.NAME.connect_timeout), [`hosts.NAME.command`](https://tuios.dev/docs/option-reference#hosts.NAME.command), [`hosts.NAME.ssh_options`](https://tuios.dev/docs/option-reference#hosts.NAME.ssh_options), [`hosts.NAME.repos_root`](https://tuios.dev/docs/option-reference#hosts.NAME.repos_root).

You can also manage the table from the shell. These commands edit the file:

```bash
tuios hosts add build gaurav@buildbox
tuios hosts test build
tuios hosts remove build
```

A change that gives a machine less applies at once, also on links that are open. A new host, a host that dials another way, or a change that gives a machine more waits for `tuios config apply` from a terminal outside TUIOS. A daemon restart also applies it. So `tuios hosts add` from a pane waits. A host that you add with "Add a host" on the settings page applies at once. See [Changes that wait](https://tuios.dev/docs/agents#changes-that-wait).

### Rules for ssh\_options

`ssh_options` accepts only options that cannot run code or write files on this machine. Write each option as `-o Keyword=value`, with one plain value and no quotes.

- Accepted examples: `-p`, `-i`, `-l`, `-J`, `Port`, `User`, `HostName`, `HostKeyAlias`, `IdentityFile`, `StrictHostKeyChecking`, the `ServerAlive` options and the algorithm lists.
- Refused: `ProxyCommand`, `LocalCommand`, the known hosts files, `ControlPath`, `-F` and socket forwards.
- Refused: port forwards (`-L`, `-R`, `-D`).
- `-J` and `ProxyJump` take host names only. `ForwardAgent` takes only `yes` or `no`.
- A host `addr` or `command` cannot start with a dash.

TUIOS drops a host with a refused option. `tuios hosts` and the Inbox name the reason. Put a refused option in `~/.ssh/config`, and name that host in `addr`.

```toml
[hosts.build]
addr = "gaurav@buildbox"
ssh_options = ["-J", "bastion", "-o", "ServerAliveInterval=30"]
```

> **Upgrading from v0.8.0.** After the upgrade, look in the Inbox or run `tuios hosts`. A host with a refused option is dropped. Move the option, such as `ProxyCommand` or `LocalForward`, into `~/.ssh/config`. Keep port forwards in `~/.ssh/config` too.

The daemon runs ssh with `BatchMode` on, so a link never asks for a password or about a host key. Run ssh to the host once by hand to accept its key.

### Files over a link

A machine with `files` can read your files and write new ones. Three keys in its `[hosts.NAME]` table set the limits:

```toml
[hosts.laptop]
allow = ["list", "files"]
files_roots = ["~/Downloads/tuios", "~/dev"]   # where it may write
files_read_roots = ["~/share"]                 # where it may read
files_min_free = "5GiB"                        # the space a write must leave free
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`hosts.NAME.files_roots`](https://tuios.dev/docs/option-reference#hosts.NAME.files_roots), [`hosts.NAME.files_read_roots`](https://tuios.dev/docs/option-reference#hosts.NAME.files_read_roots), [`hosts.NAME.files_min_free`](https://tuios.dev/docs/option-reference#hosts.NAME.files_min_free), [`hosts.NAME.files_max_entries`](https://tuios.dev/docs/option-reference#hosts.NAME.files_max_entries).

A path is absolute or starts with `~`. Some places are always closed, whatever the roots say:

- **Writes** never go into `~/.ssh`, `~/.gnupg`, cloud and git credentials, shell start files such as `.bashrc` and `.zshrc`, login items, crontabs, `/proc`, or tuios's own config and state.
- **Reads** never return keys, credentials, keyrings, shell histories, browser profiles, `/proc`, or tuios's own state. A public `*.pub` key in `~/.ssh` is the one exception.
- Reads also never return `~/.gitconfig`, `~/.config/git`, shell start files or `~/.config/environment.d`. The list also covers the snap and flatpak browser folders, Thunderbird, Signal, Discord, Slack, Telegram, VS Code and common crypto wallets. A folder copy over a link leaves these entries out.
- A file with more than one name (a hard link) is never read over a link. Copy it to a new file to share it.

The read rules and `files_read_roots` also apply to a kitty image that a program names by path in a pane that runs on this machine for the other machine. See [Kitty images in the pane](https://tuios.dev/docs/remote-hosts#kitty-images-in-the-pane).

A refused write says where writes may land and which key to change. A deny list can never name every secret on a machine, so `files_read_roots` is the stronger choice.

Other limits:

- One machine may have at most 8 write streams and 64 unfinished copies here at once. Past that, a write is `busy`, and a copy waits and tries again.
- Files dropped on a pane go to a private drop folder. It holds at most 256 MiB for all drops, for 24 hours.
- A copy another machine starts here keeps to the same rules, also after tuios restarts. When `files` is taken away, its copies here stop.
- A change that widens `files_roots` or `files_read_roots`, removes `files_read_roots`, or lowers `files_min_free` waits for `tuios config apply`. A change that narrows applies at once.
- A file that another machine writes here gets the sender's permission bits under this machine's umask. It never gets group or world write. The execute bits stay. This holds for a paired device too.
- A machine with `files` cannot write the config folders of the agent tools that tuios integrates. It also cannot read the logins and API keys of more agent tools and cloud tools.

> **Give files only to machines you trust.** A machine with `files` can write any file inside its roots and read any file outside the deny list. A file copy can run code: a binary in a folder on your `PATH`, or a config file that a program reads. Give `files`, and a wide `files_roots`, only to a machine you trust as you trust your own.

See [Remote Hosts](https://tuios.dev/docs/remote-hosts#copy-files-between-machines) for the copies themselves.

### Using a linked host

Once a host is linked, you can list its sessions and agents (`tuios ls --all-hosts`, `tuios list-agents --host build`), attach to or create sessions on it (`tuios attach --host build api`, `tuios new --host build`), and open a pane whose process runs there (`tuios new-window --host build`). See [`tuios hosts`](https://tuios.dev/docs/cli-reference/commands-for-other-machines#commands-for-other-machines).

### Reaching a host you cannot ssh to directly

A host behind NAT, with no port forward and no jump host, is a network problem to solve under TUIOS. Any tool that pipes stdio to a remote port works as an ssh `ProxyCommand`. `ssh_options` refuses `ProxyCommand`, so name it in `~/.ssh/config`.

Tailscale's [tailcat](https://github.com/tailscale/tailcat) is one such tool. It carries a connection over WireGuard with no Tailscale account and no open port. Run it on the far side against sshd:

```sh
tailcat --serve=22
```

Then add a host to `~/.ssh/config` that uses it:

```text
Host laptop-tailcat
    HostName laptop
    User gaurav
    ProxyCommand tailcat <token> 22
```

Name that host in the host entry:

```toml
[hosts.laptop]
addr = "laptop-tailcat"
```

ssh still decides who may connect: the tunnel only carries bytes to sshd, which asks for your key as usual. A leaked tailcat token gives reachability, not access. TUIOS adds no identity system of its own and opens no listening port.

## The `[tailscale]` table

`[tailscale]` changes which tailnet machines `tuios hosts add` and `tuios hosts tailnet` offer as addresses. It never adds a host by itself.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`tailscale.enabled`](https://tuios.dev/docs/option-reference#tailscale.enabled), [`tailscale.addr`](https://tuios.dev/docs/option-reference#tailscale.addr), [`tailscale.user`](https://tuios.dev/docs/option-reference#tailscale.user), [`tailscale.users`](https://tuios.dev/docs/option-reference#tailscale.users), [`tailscale.os`](https://tuios.dev/docs/option-reference#tailscale.os), [`tailscale.offline`](https://tuios.dev/docs/option-reference#tailscale.offline), [`tailscale.self`](https://tuios.dev/docs/option-reference#tailscale.self), [`tailscale.shared`](https://tuios.dev/docs/option-reference#tailscale.shared), [`tailscale.include`](https://tuios.dev/docs/option-reference#tailscale.include), [`tailscale.exclude`](https://tuios.dev/docs/option-reference#tailscale.exclude), [`tailscale.max`](https://tuios.dev/docs/option-reference#tailscale.max), [`tailscale.socket`](https://tuios.dev/docs/option-reference#tailscale.socket).

```toml
[tailscale]
user = "ubuntu"
exclude = ["*-pad-*"]

[tailscale.users]
build = "admin"
```

## The `[agents]` table

`[agents]` sets how TUIOS treats the coding agents in its panes. Except for `enabled`, it is outside `list-options`, and `set-config` cannot change it, so a program in a pane cannot loosen it. The daemon reads it at start and again whenever the file changes. See [Inbox and Review](https://tuios.dev/docs/agent-inbox) for what each part does.

### Agents that stop reporting

A hooked agent reports at each prompt and each tool call. When an agent that reported `working` sends no report for `silent_after`, tuios shows it as `unknown` with the reason `silent`. Its row reads "No report for N min".

```toml
[agents]
silent_after = "10m"   # default; "0" or "off" turns it off
```

The value is a Go duration, such as `90s` or `20m`. A value that does not parse reads as `10m`, with a warning. The daemon reads the value when it starts and when the file changes. See [Agents that stop reporting](https://tuios.dev/docs/agent-inbox#agents-that-stop-reporting).

### Card preview

Space on a card of the [task board](https://tuios.dev/docs/task-boards#the-card-preview) shows the card whole. `card_preview` says where:

```toml
[agents]
card_preview = "auto"     # "side", "sheet", "auto" or "off"
card_preview_width = ""   # the side panel: cells ("70") or a share ("40%"); empty is 40%
```

`side` puts it in a panel beside the columns, `sheet` over them, and `auto` beside them on a screen 140 columns or wider that keeps three columns, over them otherwise. `off` never shows it. The panel is 40% of the view by default, at least 44 and at most 96 cells. A drag on its edge sets the width, and the view keeps it. A double click on the edge gives the width back to `card_preview_width`.

### The other agent tables

```toml
[agents.approvals]
enabled = ["claude-code", "opencode"]   # harnesses whose permission prompts the Inbox may answer
hold_seconds = 120                      # 10 to 300
hold_plans = true                       # a plan follows enabled

[agents.approvals.risk]
builtin = true                          # keep the shipped risk rules
panes_may_allow = false                 # a pane with the respond grant may not allow a risky call

[[agents.approvals.risk.rule]]
name = "kubectl apply"
tools = ["Bash"]                        # empty: every tool
pattern = '\bkubectl\s+(apply|delete)\b'   # RE2, matched per command

[agents.permissions]
mode = "strict"                         # open (default) or strict
grants = ["read", "write", "fan"]       # what a pane holds under strict

[agents.recap]
mode = "toast"                          # toast, inbox or off
away = "10m"
test_patterns = ["go test", "pytest"]

[agents.queue]
max = 8                                 # at most 64

[agents.mail]
wake = true                             # type one line into an idle agent with unread mail

[agents.checkpoints]
enabled = true
keep = 50                               # at most 1000
max_untracked_mb = 50                   # a negative value means no limit
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`agents.approvals.enabled`](https://tuios.dev/docs/option-reference#agents.approvals.enabled), [`agents.approvals.hold_seconds`](https://tuios.dev/docs/option-reference#agents.approvals.hold_seconds), [`agents.approvals.hold_plans`](https://tuios.dev/docs/option-reference#agents.approvals.hold_plans), [`agents.approvals.risk.builtin`](https://tuios.dev/docs/option-reference#agents.approvals.risk.builtin), [`agents.approvals.risk.panes_may_allow`](https://tuios.dev/docs/option-reference#agents.approvals.risk.panes_may_allow), [`agents.approvals.risk.rule`](https://tuios.dev/docs/option-reference#agents.approvals.risk.rule), [`agents.permissions.mode`](https://tuios.dev/docs/option-reference#agents.permissions.mode), [`agents.permissions.grants`](https://tuios.dev/docs/option-reference#agents.permissions.grants), [`agents.recap.mode`](https://tuios.dev/docs/option-reference#agents.recap.mode), [`agents.recap.away`](https://tuios.dev/docs/option-reference#agents.recap.away), [`agents.recap.test_patterns`](https://tuios.dev/docs/option-reference#agents.recap.test_patterns), [`agents.queue.max`](https://tuios.dev/docs/option-reference#agents.queue.max), [`agents.mail.wake`](https://tuios.dev/docs/option-reference#agents.mail.wake), [`agents.mail.questions_to_parent`](https://tuios.dev/docs/option-reference#agents.mail.questions_to_parent), [`agents.checkpoints.enabled`](https://tuios.dev/docs/option-reference#agents.checkpoints.enabled), [`agents.checkpoints.keep`](https://tuios.dev/docs/option-reference#agents.checkpoints.keep), [`agents.checkpoints.max_untracked_mb`](https://tuios.dev/docs/option-reference#agents.checkpoints.max_untracked_mb), [`agents.presets.NAME`](https://tuios.dev/docs/option-reference#agents.presets.NAME).

After turning on `approvals.enabled`, run `tuios integration install` for that harness again, so its hook is the version that waits. The grants are `read`, `write`, `fan`, `respond`, `files` and `admin`. See [What a pane may do](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/AGENT_STATE.md#what-a-pane-may-do).

A change to `[agents.permissions]` that gives panes less applies at once. A change that gives more, such as `strict` to `open`, waits. Run `tuios config apply` from a terminal outside TUIOS, or restart the daemon. See [Changes that wait](https://tuios.dev/docs/agents#changes-that-wait).

## The `[notify]` table

`[notify]` sends a push notification when the Inbox gets an item that waits for you. The daemon sends it, so it works when no client is attached. The providers are ntfy, Pushover and a webhook.

```toml
[notify]
web_url = "https://term.example.com/"   # tuios-web, for a link to the item

[notify.ntfy]
url = "https://ntfy.sh/a-long-random-topic"
token_file = "~/.config/tuios/ntfy-token"   # optional
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`notify.enabled`](https://tuios.dev/docs/option-reference#notify.enabled), [`notify.web_url`](https://tuios.dev/docs/option-reference#notify.web_url), [`notify.content`](https://tuios.dev/docs/option-reference#notify.content), [`notify.quiet_active_seconds`](https://tuios.dev/docs/option-reference#notify.quiet_active_seconds), [`notify.cooldown_seconds`](https://tuios.dev/docs/option-reference#notify.cooldown_seconds), [`notify.max_per_hour`](https://tuios.dev/docs/option-reference#notify.max_per_hour), [`notify.allow_http_redirects`](https://tuios.dev/docs/option-reference#notify.allow_http_redirects).

`[notify.triggers]` selects the Inbox kinds: `approval`, `plan`, `question` and `ask` are on by default, `mail`, `errored` and `finished` are off. Like `[hosts]`, `[notify]` is not in `list-options`, and `tuios set-config` cannot change it. A new address or a new source for a secret waits for `tuios config apply` from a terminal outside TUIOS. `tuios notify test` sends a test notification through each provider. See [Push Notifications](https://tuios.dev/docs/push-notifications) for the providers and the secrets.

### Web Push

`[notify.webpush]` configures the pushes the daemon sends to a phone that registered for Web Push. It needs no provider.

```toml
[notify.webpush]
subject = "https://example.com/tuios-contact"   # optional
allow_insecure = false
```

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`notify.webpush.subject`](https://tuios.dev/docs/option-reference#notify.webpush.subject), [`notify.webpush.allow_insecure`](https://tuios.dev/docs/option-reference#notify.webpush.allow_insecure).

See [Push Notifications](https://tuios.dev/docs/push-notifications#web-push-to-a-phone).

## Hooks: the `[hooks]` table

`[hooks]` runs shell commands on window, workspace, session and agent events. Event names use hyphens, such as `after-new-window`. See [Hooks](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/HOOKS.md) and `tuios list-hooks`.

## The `[links]` table

`[[links.rules]]` turns text in a pane into a link: `regex` is a regular
expression in Go syntax, and `url` is the address a match opens. `$0` is the
whole match, and `$1`, `$2` or `${name}` are its groups. A real URL wins over a
rule, and an earlier rule wins over a later one. See [Link rules](https://tuios.dev/docs/configuration/files-input-and-focus#link-rules).

## The `[mermaid]` table

`[mermaid]` sets the colours and the background of `tuios mermaid`. See
[Mermaid diagram colours](https://tuios.dev/docs/configuration/motion-rendering-and-themes#mermaid-diagram-colours).

## The `[plugins]` table

`[plugins]` says which plugins tuios runs.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`plugins.enabled`](https://tuios.dev/docs/option-reference#plugins.enabled), [`plugins.dirs`](https://tuios.dev/docs/option-reference#plugins.dirs).

See [PLUGINS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/PLUGINS.md).
