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. The Configuration page lists every part.

Limits and banners

These options are in the option reference: notifications.rate_limit_ms, notifications.bell_rate_limit_ms, appearance.copy_search_max_matches, tape.banner_ms, tape.done_linger_ms.

[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: appearance.multi_copy_dim, appearance.sidebar.marquee_pause_ms, appearance.sidebar.marquee_step_ms, dock.meter_interval_ms.

[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: appearance.idle_fps, appearance.sidebar.git_refresh_ms, debug.show_key_count.

[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: appearance.whichkey_delay_ms, appearance.tooltip_delay_ms, appearance.zen_reveal_ms, appearance.paste_preview_ms, appearance.chord_timeout_ms.

[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: mouse.double_click_ms, mouse.drag_threshold.

[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). 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:

[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:

[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.

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.

[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:

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:

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.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page