# Display, mouse and shell

URL: https://tuios.dev/docs/configuration/display-mouse-and-shell

> Display, mouse and shell: 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.

## Limits and banners

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`notifications.rate_limit_ms`](https://tuios.dev/docs/option-reference#notifications.rate_limit_ms), [`notifications.bell_rate_limit_ms`](https://tuios.dev/docs/option-reference#notifications.bell_rate_limit_ms), [`appearance.copy_search_max_matches`](https://tuios.dev/docs/option-reference#appearance.copy_search_max_matches), [`tape.banner_ms`](https://tuios.dev/docs/option-reference#tape.banner_ms), [`tape.done_linger_ms`](https://tuios.dev/docs/option-reference#tape.done_linger_ms).

```toml
[notifications]
rate_limit_ms = 1000

[appearance]
copy_search_max_matches = 5000

[tape]
banner_ms = 4000
```

A value of 0 on `copy_search_max_matches`, `banner_ms` or `done_linger_ms` is read
as the default, and a value out of range moves to the nearest end of the range.
All five are on the settings page and apply at once.

## More display options

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.multi_copy_dim`](https://tuios.dev/docs/option-reference#appearance.multi_copy_dim), [`appearance.sidebar.marquee_pause_ms`](https://tuios.dev/docs/option-reference#appearance.sidebar.marquee_pause_ms), [`appearance.sidebar.marquee_step_ms`](https://tuios.dev/docs/option-reference#appearance.sidebar.marquee_step_ms), [`dock.meter_interval_ms`](https://tuios.dev/docs/option-reference#dock.meter_interval_ms).

```toml
[appearance]
multi_copy_dim = 60

[appearance.sidebar]
marquee_pause_ms = 400
marquee_step_ms = 150

[dock]
meter_interval_ms = 5000
```

A value of 0 on `marquee_step_ms` or `meter_interval_ms` is read as the default,
and a value out of range moves to the nearest end of the range. All four are on
the settings page and apply at once.

## Display options

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.idle_fps`](https://tuios.dev/docs/option-reference#appearance.idle_fps), [`appearance.sidebar.git_refresh_ms`](https://tuios.dev/docs/option-reference#appearance.sidebar.git_refresh_ms), [`debug.show_key_count`](https://tuios.dev/docs/option-reference#debug.show_key_count).

```toml
[appearance]
idle_fps = 4

[appearance.sidebar]
git_refresh_ms = 5000

[debug]
show_key_count = 8
```

A value of 0 is read as the default, and a value out of range moves to the
nearest end of the range. All three are on the settings page and apply at once.

## Timing options

These `[appearance]` options set how long the interface waits before it acts.
Each is in milliseconds, applies at once, and is on the settings page.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.whichkey_delay_ms`](https://tuios.dev/docs/option-reference#appearance.whichkey_delay_ms), [`appearance.tooltip_delay_ms`](https://tuios.dev/docs/option-reference#appearance.tooltip_delay_ms), [`appearance.zen_reveal_ms`](https://tuios.dev/docs/option-reference#appearance.zen_reveal_ms), [`appearance.paste_preview_ms`](https://tuios.dev/docs/option-reference#appearance.paste_preview_ms), [`appearance.chord_timeout_ms`](https://tuios.dev/docs/option-reference#appearance.chord_timeout_ms).

```toml
[appearance]
whichkey_delay_ms = 1000
chord_timeout_ms = 800
```

A value of 0 on `zen_reveal_ms`, `paste_preview_ms` or `chord_timeout_ms` is read
as the default, and a value out of range moves to the nearest end of the range.

## Mouse

The `[mouse]` table sets how tuios reads the pointer's gestures.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`mouse.double_click_ms`](https://tuios.dev/docs/option-reference#mouse.double_click_ms), [`mouse.drag_threshold`](https://tuios.dev/docs/option-reference#mouse.drag_threshold).

```toml
[mouse]
double_click_ms = 450
drag_threshold = 8
```

Raise `double_click_ms` for a slow hand or a trackpad that spaces its clicks.
The Agents list used 400 ms before this option; it now follows the same value
as the pane, 300 ms by default. Both options are on the settings page, in the
Behavior section, and apply at once. A value of 0 or a value out of range is
read as the default or moved to the nearest end of the range.

## Shell integration

tuios turns on OSC 133 prompt marks in the bash and zsh shells that it starts
in panes, as Ghostty and kitty do. The marks tell tuios where a prompt starts,
where a command starts, and how the command 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**: tuios starts zsh with `ZDOTDIR` set to a folder of its own. The
  `.zshenv` there sets `ZDOTDIR` back to your value, reads your `.zshenv`, and
  adds the marks. zsh then reads your `.zshrc` as usual, and your `.zprofile`
  and `.zlogin` too when it is a login shell (see [Login shells](https://tuios.dev/docs/configuration/display-mouse-and-shell#login-shells)).
  Programs in the pane see your own `ZDOTDIR`.
- **bash**: tuios starts bash with `--rcfile` set to a file of its own. That
  file reads your `~/.bashrc` and then adds the marks. Your `PS1`, `PS0`,
  `PROMPT_COMMAND` (a string or an array), traps, `BASH_ENV` and `set -e` or
  `set -u` stay as they are. This needs bash 4.4 or newer. An older bash
  starts with no marks.
- **fish 4** and **nushell** send the marks themselves, so tuios adds nothing.
- Other shells start as they are.

When your own setup already sends a mark, for example from a prompt theme or
your own `precmd`, tuios does not send that mark again.

The files are in `$XDG_STATE_HOME/tuios/shell-integration`, by default
`~/.local/state/tuios/shell-integration`. tuios writes them once and checks
them the first time it starts a shell. A shell starts less than 1 ms slower.

To turn it off:

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

The change applies to new panes. To choose for one pane, use
`tuios new-window --shell-integration off`, or `auto` when the config is off.
`tuios doctor shell` shows which panes send marks.

tuios does not set up the shell of a remote pane: a pane that runs `ssh`, or a
window on another machine (`--host`). To get marks there, add the lines that
`tuios doctor shell` prints to the rc file on that machine. Then open a new
pane.

## Login shells

By default tuios starts the shell of a new pane as an interactive shell that
is not a login shell. Such a shell reads `.zshrc` or `.bashrc`, but not
`.zprofile`, `.bash_profile` or `.profile`. Most terminals on macOS start a
login shell, so a `PATH` that you set in `.zprofile` can be missing in tuios.

To start each new pane as a login shell:

```toml
[shell]
login = true   # default: false
```

- **zsh** and **fish** start with `-l`. zsh then reads `.zprofile` and
  `.zlogin`.
- **bash** keeps the file that tuios uses for the prompt marks, because a
  login bash reads no rc file. That file reads `/etc/profile` and then the
  first of `~/.bash_profile`, `~/.bash_login` and `~/.profile`, as a login bash
  does, in place of `~/.bashrc`. Most `~/.bash_profile` files read `~/.bashrc`
  themselves. With `[shell] integration = "off"`, bash starts with `-l`.
- Other shells (`sh`, `dash`, `ksh`, `tcsh`) start with a `-` in front of
  their name, which every Unix shell reads as a login shell.
- On Windows the option does nothing.

The change applies to new panes. A pane that runs a command, such as
`tuios new-window -- htop`, runs the command as it is.

## Splits that follow ssh

The actions `split_ssh_horizontal`, `split_ssh_vertical` and `new_window_ssh`
open a pane on the machine that the focused pane is connected to with ssh. See
[KEYBINDINGS.md](https://tuios.dev/docs/keybindings/panes-panels-and-workspaces#split-into-the-same-ssh).

[`appearance.new_window_follow_ssh`](https://tuios.dev/docs/option-reference#appearance.new_window_follow_ssh) makes the ordinary actions do the same:
`split_horizontal`, `split_vertical` and `new_window`. When the focused pane
does not run ssh, these actions open an ordinary pane. The default is `false`.

```toml
[appearance]
new_window_follow_ssh = true
```

tuios finds ssh in the foreground of the pane. ssh can run from a shell, or
from `sshpass`, `autossh` or `mosh`. ssh can also run from another program,
such as your own helper script (`tt ssh box`). tuios then follows only an
interactive login: an ssh line with no remote command, and with none of `-s`,
`-N`, `-T` or `-W`. tuios reads only the processes that you own in the pane. It runs the `ssh` or `mosh` that it finds on its own `PATH`,
with no shell on this machine. It never runs the program that the pane runs.

The new ssh gets the same environment as an ordinary new pane. If the ssh
that tuios follows has an `SSH_AUTH_SOCK` that names your own agent socket,
the new ssh gets that value too. An agent that your shell started in the pane
then works in the split. The socket must not be a link, and its folder must
be yours and closed to other users.

The new ssh line keeps only what it needs to reach the same host as the same
user. It always gets `-o ControlMaster=no`. Your `~/.ssh/config` applies to it
as usual, so a setting that you put there still works in the split.

### Lines that are not followed

tuios follows an ssh line only when each `-o` option is on one of two lists.
The new pane keeps these options:

`AddressFamily`, `BatchMode`, `CertificateFile`, `CheckHostIP`, `Ciphers`,
`Compression`, `ConnectionAttempts`, `ConnectTimeout`, `EscapeChar`,
`HostKeyAlgorithms`, `HostName`, `IdentitiesOnly`, `IdentityFile`,
`KbdInteractiveAuthentication`, `KexAlgorithms`, `LogLevel`, `MACs`,
`PasswordAuthentication`, `Port`, `PreferredAuthentications`, `ProxyJump`,
`PubkeyAcceptedAlgorithms`, `PubkeyAuthentication`, `ServerAliveCountMax`,
`ServerAliveInterval`, `StrictHostKeyChecking`, `TCPKeepAlive` and `User`.

The new pane does not get these options, and tuios still follows the line:

- Forwards and sessions: `LocalForward`, `RemoteForward`, `DynamicForward`,
  `GatewayPorts`, `ExitOnForwardFailure`, `ClearAllForwardings`, `Tunnel`,
  `TunnelDevice`, `RemoteCommand`, `SessionType`, `StdinNull`,
  `ForkAfterAuthentication` and `RequestTTY`.
- Files, sockets, environment and forwarding: `ControlMaster`,
  `ControlPersist`, `ControlPath`, `UserKnownHostsFile`,
  `GlobalKnownHostsFile`, `HostKeyAlias`, `IdentityAgent`, `SendEnv`,
  `SetEnv`, `ForwardAgent`, `ForwardX11` and `ForwardX11Trusted`.
- The flags `-A`, `-X`, `-Y`, `-S`, `-L`, `-R`, `-D`, `-W`, `-w`, `-N`, `-f`,
  `-n`, `-T`, `-t`, `-M` and `-s`.

These ssh lines get an ordinary pane:

- An `-o` option that is not on the two lists above. `ProxyCommand`,
  `LocalCommand`, `XAuthLocation` and `Match` are examples.
- An option or a value with a control character, such as a line break.
- `-E`, `-F`, `-I`, `-G`, `-V`, `-Q` and `-O`, and an option that tuios does
  not know.
- A `-J` or `ProxyJump` hop that is not `[user@]host[:port]` or the `ssh://`
  form, made of letters, digits and `._:@[]-`, or a hop that starts with `-`.
- A mosh destination that starts with `-`.
- mosh with `--ssh`, `--client` or `--server`.
- ssh that a file transfer starts: `scp`, `rsync`, `git`, `sftp` or `sshfs`.
- ssh that another program starts, when the line has a remote command, or
  `-s`, `-N`, `-T` or `-W`.

When a split asks to follow ssh and gets an ordinary pane, the dock says why.

Put a `ProxyCommand` or a `ProxyJump` in `~/.ssh/config` to use it with a
split. A split with `-J` on the command line is followed.

### Start in the remote folder

The new pane starts in the remote folder when the remote shell reports its
folder with OSC 7. The host name in the report must be the same as the host
in the ssh line, or as the `HostName` that `ssh -G` gives for that line.
`reachy-mini` matches `pollen@reachy-mini`. When `~/.ssh/config` makes `prod`
an alias for `box.example.com`, a report from `box.example.com` or from `box`
matches `ssh prod`. A report from `box.other.com` does not. When there is no
match, the new pane starts in the remote home folder.

fish sends the report by default. For bash, add this line to `~/.bashrc` on
the remote machine:

```bash
PROMPT_COMMAND='printf "\033]7;file://%s%s\033\\" "$HOSTNAME" "$PWD"'${PROMPT_COMMAND:+;$PROMPT_COMMAND}
```

For zsh, add these lines to `~/.zshrc` on the remote machine:

```zsh
autoload -Uz add-zsh-hook
_tuios_osc7() { printf '\e]7;file://%s%s\e\\' "$HOST" "$PWD" }
add-zsh-hook precmd _tuios_osc7
```

To go to the folder, tuios adds `-t`, `-o RemoteCommand=none` and the
command `exec sh -c 'cd "FOLDER" ...'` to ssh. This works with every login
shell that can start `sh`. If the folder is gone, the new pane starts in the
home folder. A folder name with a quote, `$`, a backslash or `!` is not used.
