README

TUIOS: Terminal UI Operating System

  
  
  
  
  



  
  


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


Table of Contents


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




 Installation

 Package Managers

Homebrew (macOS/Linux):
bash
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.
bash
brew uninstall tuios
brew install gaurav-gosain/tap/tuios-ghostty


Arch Linux (AUR):
bash
yay -S tuios-bin


Nix:
bash
nix run github:Gaurav-Gosain/tuios/v0.10.1tuios    a release
nix run github:Gaurav-Gosain/tuiostuios           the latest main
nix run nixpkgstuios                              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

bash
 Quick install script (Linux/

Top issues

Discussions

Latest release

tuios 0.12.1 fixes a crash on the task board and makes right-click Preview work from any pane. The rail now shows the names your agents set. The drop preview is now only a frame by default.

 Install

bash
brew install tuios                      Homebrew (macOS, Linux)
yay -S tuios-bin                        AUR (tuios-web-bin for the web server)
nix run github:Gaurav-Gosain/tuios      Nix
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash
go install github.com/Gaurav-Gosain/tuios/cmd/[email protected]
docker run -it --rm ghcr.io/gaurav-gosain/tuios:v0.12.1


A