tuios

TUIOS is a modern terminal multiplexer and window manager built with Go. It provides a vim-like modal interface with multiple terminal panes, workspaces, BSP tiling, kitty graphics protocol support, and a command palette, all running inside your existing terminal. A daemon keeps sessions alive, reaches sessions on your other machines, and lets the coding agents in your panes report their state and message each other.

Built on the Charm stack (Bubble Tea v2, Lipgloss v2), TUIOS features event-driven rendering for near-zero idle CPU usage, flicker-free kitty image passthrough, and comprehensive keyboard/mouse interaction.

Documentation

Full documentation is available at tuios.dev (hosted) or in the docs/ folder. To try tuios without installing it, take the guided tour at tuios.dev/learn: the real app, compiled to WebAssembly, with a practice shell in every pane. Already installed it? Run tuios tutor for the same tour in your own terminal. It changes nothing on your machine.

What changed in v0.10.1 is in the release notes.

Quick Links

• Getting Started: Install and first session
• Keybindings: Default keys and how to rebind them
• BSP Tiling: Tiling with preselection and split control
• Layout Modes: BSP, master-stack and scrolling layouts, aggregate view, multifocus
• Configuration: Customize keybindings, themes, and behavior
• Hooks: Run shell commands on window, session and agent events
• Themes: Built-in themes and custom theme JSON
• Glyph sets: The characters the chrome is drawn with
• CLI Reference: All command-line options
• Tape Scripting: Automate workflows
• Sessions: Daemon mode, attach/detach, other machines, and what survives
• Agents: Running coding agents in tuios: state, the Inbox, approvals, fleets, other machines, grants and MCP
• Program Status: OSC 7501 from any program, tuios status, and the reports tuios sends to its own terminal
• tmux Shim: Run tools that drive tmux, such as Claude Code agent teams
• Control Protocol: JSON verb protocol for driving the daemon
• Architecture: Technical design

• Installation
• Features
• Quick Start
• Architecture
• Performance
• Development
• Contributors
• License

Installation

Package Managers

Homebrew (macOS/Linux):

brew install tuios

Homebrew, ghostty build (Linux only): tuios built with the libghostty-vt emulator. It installs a binary with the same name as the tuios formula. Uninstall the formula first.

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

Arch Linux (AUR):

yay -S tuios-bin

Nix:

nix run github:Gaurav-Gosain/tuios/v0.10.1#tuios   # a release
nix run github:Gaurav-Gosain/tuios#tuios          # the latest main
nix run nixpkgs#tuios                             # the nixpkgs package

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

Other Methods

# Quick install script (Linux/macOS, and Windows from Git Bash or PowerShell with WSL)
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash

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

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

GitHub Releases: Pre-built binaries for Linux, macOS, Windows, FreeBSD and OpenBSD, with a checksums.txt. The tuios-ghostty_* archives are tuios built on the libghostty-vt emulator, for Linux, macOS and Windows on amd64 and arm64.

Building from source needs Go 1.26.8 or newer.

Updating. If you installed with the quick install script or a release binary, tuios update fetches the newest release and puts it in place (tuios update --check just reports). Everything else has a package manager that owns the binary, so use that instead; tuios update detects which you have and prints the right command rather than overwriting it.

Images on Windows. The console host built into Windows drops sixel images before tuios sees them. To let them through, take conpty.dll and OpenConsole.exe for the architecture of your tuios.exe (x64, x86 or arm64) from the Microsoft.Windows.Console.ConPTY package, at runtimes/win-<arch>/native/conpty.dll and build/native/runtimes/<arch>/OpenConsole.exe, and put both in the folder that holds tuios.exe. tuios then opens panes through them, as Windows Terminal does. Without both files, panes use the built-in ConPTY. The daemon looks for the two files when it starts, so run tuios kill-server after adding them.

Shell Completions

tuios completion <shell> prints a completion script for bash, zsh, fish or PowerShell. Besides subcommands and flags, it completes values such as session names for --session and configured hosts for --host.

# Bash (needs the bash-completion package)
tuios completion bash > ~/.local/share/bash-completion/completions/tuios

# Zsh (the directory must be on your $fpath, before compinit runs)
tuios completion zsh > "${fpath[1]}/_tuios"

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

# PowerShell: add this line to your $PROFILE
tuios completion powershell | Out-String | Invoke-Expression

Start a new shell afterwards. Run tuios completion <shell> --help for more options, or see the CLI reference.

Requirements: A terminal with true color support. Kitty graphics and sixel support recommended (Ghostty, Kitty, WezTerm).

Features

Each picture is a capture that tuios made of itself. Click one to read its docs page.

Core

• Multiple Terminal Panes: Create, resize, drag, and organize terminal sessions
• 9 Workspaces: Independent workspace isolation with instant switching
• Modal Interface: Vim-inspired Window Management and Terminal modes
• Command Palette: Fuzzy-searchable action launcher (Ctrl+P)
• Launcher: Fuzzy search everything on $PATH plus your installed desktop apps (Alt+Space), ranked by what you actually run. Enter starts it; Tab op