Skip to content

Getting Started

Jump to bottom
Gaurav Gosain edited this page Oct 17, 2026 · 10 revisions

Install TUIOS, open your first windows, and learn the keys you need on day one.

This page takes you from nothing to a working session in about five minutes.

Note

Want to try it first?

Learn tuios runs the real app in your browser, with a pretend shell. Press the keys yourself, five minutes, nothing to install.

You need a terminal with true color support. A Nerd Font makes the icons render; without one, start TUIOS with --ascii-only.

Install

Homebrew

macOS and Linux:

brew install tuios

On Linux, the tuios-ghostty cask installs tuios built with the libghostty-vt emulator. It installs a tuios binary, as the tuios formula does. Uninstall the formula before you install the cask:

brew uninstall tuios
brew install gaurav-gosain/tap/tuios-ghostty

There is no macOS ghostty cask. On macOS, use a tuios-ghostty_*_Darwin_* archive from the releases page.

The tuios cask in gaurav-gosain/tap is deprecated. brew install tuios installs the formula from Homebrew core. If you installed the cask, move to the formula:

brew uninstall --cask tuios && brew install tuios

Arch (AUR)

yay -S tuios-bin

Script

Linux and macOS. Installs the tuios binary into /usr/local/bin, ~/.local/bin or ~/bin, whichever it can write to.

curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash

Nix

nix run github:Gaurav-Gosain/tuios/v0.10.1#tuios  # a release
nix run github:Gaurav-Gosain/tuios#tuios          # the newest commit on main

Put a release tag after the repo name to build that release. Without a tag, Nix builds the newest commit on main.

The flake builds for x86_64-linux, aarch64-linux and aarch64-darwin. On an Intel Mac, use a release binary.

Go

Needs Go 1.26.6 or newer, the version go.mod names.

go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest

Docker

docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest

Pre-built binaries for Linux, macOS, Windows and FreeBSD are on the releases page.

These binaries use the pure Go terminal emulator. Archives named tuios-ghostty_* use the libghostty-vt emulator backend. From v0.8.1, they are available for Linux, Windows and macOS on Apple silicon and Intel. The v0.8.0 release had no macOS ghostty archive.

Check the install:

tuios --version

The first line names the version and the terminal emulator backend the binary was built with, for example tuios version 0.10.0 [pure-Go backend].

Note

Keeping it up to date

If you installed with the script or a release binary, tuios update installs the newest release over the binary (tuios update --check only reports). For Homebrew, AUR, Nix and Go installs, use that tool to update. tuios update detects them and prints the right command instead.

The browser terminal is a separate binary, tuios-web. See Web Terminal to install it.

Build from source

git clone https://github.com/Gaurav-Gosain/tuios.git
cd tuios
go build -o tuios ./cmd/tuios

./scripts/install.sh builds and installs into ~/.local/bin. It builds the pure Go emulator by default, which needs nothing beyond Go. Run ./scripts/install.sh ghostty for the libghostty-vt emulator backend, which needs zig.

Your first session

1. Start TUIOS

tuios

The first run creates a session called session-0 and shows a welcome screen with four keys on it:

  TUIOS
  Terminal UI Operating System

  n  new window    N  new session    ?  help    ,  settings

You are in window management mode. Keys here arrange windows. Nothing is sent to a shell yet.

The dock runs along the top edge, and the session rail down the right edge lists your sessions, panes and files, and later your agents. Ctrl+B b hides the rail.

2. Open a window

Press n. A window opens with your shell in it.

3. Type in it

Press i (or Enter) to enter terminal mode. Your keys now go to the shell. Run a command:

ls

4. Go back to window management

Press Alt+Esc (Opt+Esc on macOS), or Ctrl+B then Esc.

A bare Esc stays in terminal mode and goes to the program, so vim and other full-screen programs keep working.

5. Open two more windows

Press n twice. Tiling is on by default, so each new window takes half of the focused one and all three stay visible.

Move between them with Tab and Shift+Tab, the number keys 1 to 9, or Alt+arrow keys to move to the neighbour in that direction. You can also click a window to focus it, and double-click it to start typing in it.

6. Try another workspace

Press Alt+2 (Opt+2 on macOS) to switch to workspace 2. It is empty. Open a window there, then press Alt+1 to go back.

7. Detach, and come back

Press Ctrl+B then d. TUIOS exits, but the session and its shells keep running in the background daemon. Run tuios again and everything is where you left it.

Tip

When you forget a key

Press Ctrl+P in either mode to open the command palette and search every command by name. Press Ctrl+B and wait half a second: a panel lists every key the prefix accepts next. Ctrl+B then ? opens the full help.

The two modes

Mode What your keys do How to get there
Window management Create, close, move, tile and switch windows Alt+Esc, or Ctrl+B Esc
Terminal Go to the program in the focused window i or Enter

Ctrl+B is the prefix key. It works in both modes: press it, release it, then press the next key. You can change it with keybindings.leader_key in the configuration.

Keys for day one

On macOS, read Alt as Opt. If an Opt chord types a strange character instead, see the macOS notes.

Windows

Key Action
n New window (window mode)
w or x Close the focused window (window mode)
r Rename the focused window (window mode)
Tab / Shift+Tab Next / previous window (window mode)
Alt+N / Alt+P Next / previous window (both modes)
Alt+arrow Focus the window in that direction (both modes)
1 to 9 Focus window by number (window mode)
z Zoom the focused window over the layout, and back (window mode)
m Minimize to the dock (window mode). M restores all.

The prefix versions work in both modes: Ctrl+B then c (new), x (close), r (rename), n/p (next/previous), an arrow key (focus that way), 0 to 9 (focus by number), z (zoom).

Tiling

Key Action
t or Ctrl+B Space Turn tiling on or off
- / | Split the focused window: new window below / to the right (window mode)
H J K L Swap with the neighbour left / down / up / right (window mode)
= Make all splits equal (window mode)

BSP Tiling covers preselection, resizing and the other layouts.

Workspaces

Key Action
Alt+1 to 9 Switch to workspace 1 to 9
Alt+Shift+1 to 9 Move the focused window there, and follow it
Ctrl+B w, then a digit Switch workspace from the prefix menu

Ctrl+B followed directly by a digit focuses a window, not a workspace.

Scrollback and copying

Key Action
Mouse wheel Scroll the window's history. Typing, or scrolling back to the bottom, returns to live output.
Ctrl+B [ Enter copy mode: move with vim keys, / to search, v to select, y to copy, Esc to leave
Drag with the mouse Select text. It is copied when you release.
Ctrl+click a link Open it. See Links.

Everything else

Key Action
Ctrl+P Command palette
Alt+Space or Ctrl+B a App launcher: start any program on your $PATH in a new window
Ctrl+B S Session switcher
Ctrl+B , Settings page (, in window mode)
Ctrl+B ? Help (? in window mode)
Ctrl+B d Detach, leaving the session running
Ctrl+B q Quit menu: detach, switch session, or kill this session

The full list is on the Keybindings page, and tuios keybinds list prints the bindings in effect on your machine.

Sessions

tuios on its own attaches to the session you used last, and creates one if there is none. To manage several:

tuios new work          # create a session called "work" and attach to it
tuios ls                # list sessions
tuios attach work       # attach to "work"
tuios kill-session work # end "work" and every window in it

Inside TUIOS, Ctrl+B S switches between sessions and N (window mode) creates one.

If you want a session that lives and dies with this terminal and starts no daemon, run tuios --standalone. Sessions explains both kinds and exactly what survives a restart.

Make it yours

tuios config edit        # open the config file in $EDITOR
tuios config path        # print where it is
tuios --list-themes      # list the built-in themes
tuios --theme dracula    # start with a theme

Most settings can also be changed live on the settings page, Ctrl+B ,. See Configuration for every option.

Shell completions

# Bash
tuios completion bash > /etc/bash_completion.d/tuios

# Zsh
tuios completion zsh > "${fpath[1]}/_tuios"

# Fish
tuios completion fish > ~/.config/fish/completions/tuios.fish

# PowerShell
tuios completion powershell > tuios.ps1

Troubleshooting

Empty space around TUIOS

TUIOS fills every cell that the terminal gives it. A blank border around TUIOS comes from the padding of the terminal window, not from TUIOS. To remove it, set the padding of your terminal to zero:

Terminal Setting
kitty window_padding_width 0
Ghostty window-padding-x = 0 and window-padding-y = 0
WezTerm window_padding = { left = 0, right = 0, top = 0, bottom = 0 }
Alacritty padding = { x = 0, y = 0 } under [window]

Some terminals also leave a thin gap when the window size is not a whole number of cells. Ghostty window-padding-balance = true spreads that gap evenly.

The screen is dim except around the pointer

The spotlight is on. Press Esc in window mode, or Ctrl+B B in any mode. You can also click the Spotlight chip in the dock. See Spotlight.

No sound from agent alerts

Alerts are silent until you set notifications.agent.sound = true. With sound_mode = "bell", your terminal's bell setting decides if you hear it. See Hear an alert.

My config seems ignored

TUIOS ignores only the keys that it cannot read and loads the rest of the file. Open the log viewer with Ctrl+B D l, or run tuios keybinds doctor, to see each ignored key. See My config seems ignored on tuios.dev.

The paste did not arrive

TUIOS tells you why the daemon refused a paste: The daemon was busy. Try again., The paste is too large. or This pane does not allow pastes. See The paste did not arrive on tuios.dev.

Next steps

tuios.dev · Edit the source in tuios-docs · MIT License

Home

Windows and Layout

Sessions and Machines

Agents

Scripting

Recording

Reference

Clone this wiki locally