tuios

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./assets/brand/banner-dark.png"> <source media="(prefers-color-scheme: light)" srcset="./assets/brand/banner-light.png"> <img alt="tuios: a terminal window manager that knows what your agents are doing. Tilly, a small purple CRT whose screen is a tiled layout, stands beside the tuios wordmark and a tiled terminal session." src="./assets/brand/banner-light.png" width="100%"> </picture> <p><strong>TUIOS: Terminal UI Operating System</strong></p>

<a href="https://github.com/Gaurav-Gosain/tuios/releases"><img src="https://img.shields.io/github/release/Gaurav-Gosain/tuios.svg" alt="Latest Release"></a> <a href="https://pkg.go.dev/github.com/Gaurav-Gosain/tuios?tab=doc"><img src="https://godoc.org/github.com/Gaurav-Gosain/tuios?status.svg" alt="GoDoc"></a> <a href="https://deepwiki.com/Gaurav-Gosain/tuios"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a> <br> <a title="This tool is Tool of The Week on Terminal Trove, The $HOME of all things in the terminal" href="https://terminaltrove.com/"><img src="https://cdn.terminaltrove.com/media/badges/tool_of_the_week/png/terminal_trove_tool_of_the_week_green_on_dark_grey_bg.png" alt="Terminal Trove Tool of The Week" style="width: 250px;" /></a>

</div>

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.

What changed in v0.8.4 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
• 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

<details> <summary>Table of Contents</summary> <!--toc:start-->

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

<!--toc:end--> </details>

Installation

Package Managers

Homebrew (macOS/Linux):

brew install tuios

Arch Linux (AUR):

yay -S tuios-bin

Nix:

nix run github:Gaurav-Gosain/tuios/v0.8.4#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)
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.6 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.

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

Features

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 (<kbd>Ctrl</kbd>+<kbd>P</kbd>)
• Launcher: Fuzzy search everything on $PATH plus your installed desktop apps (<kbd>Alt</kbd>+<kbd>Space</kbd>), ranked by what you actually run. <kbd>Enter</kbd> starts it; <kbd>Tab</kbd> opens a shell with the command typed but not entered, so you can add arguments. App icons are drawn where the terminal supports kitty graphics.
• Pane Zoom: Zoom any pane with <kbd>z</kbd> (WM mode) or <kbd>Prefix</kbd>+<kbd>z</kbd>. It takes 95% of the screen by default; set appearance.zoom_size = 100 for fullscreen. A fullscreen zoom hides the shared borders, and the dockbar shows a Z indicator.
• Session Rail: A sidebar with sessions, terminals, files, git state and agents, on by default on the right (appearance.sidebar.enabled)
• Settings Page: Change options in the app with <kbd>Prefix</kbd>+<kbd>,</kbd>
• Popups: tuios popup -- fzf runs a command in a floating pane that closes when it exits

Agents

The guide is docs/AGENT_STATE.md.

• Agent State: Panes running a coding agent show whether it is working, waiting for you, done or errored, as a shape in the title and a row on the rail. tuios integration install wires 19 harnesses (Claude Code, Codex, Gemini CLI, opencode and more) to report it, and tuios detects 24 agent CLIs by their process and screen
• Inbox: <kbd>Prefix</kbd>+<kbd>i</kbd> lists everything waiting for you in every session and on every machine: approvals, questions, mail, errors, finished turns. <kbd>Prefix</kbd>+<kbd>o</kbd> jumps to the oldest. Answer a prompt from there without going to the pane, and with [agents.approvals] answer Claude Code, opencode, Kilo and Qwen Code permission requests with one key
• Questions and Messages: tuios ask-human puts a question with fixed answers in your Inbox. Agents mail each other with tuios send-agent-message, and tuios ask-agent asks one and waits for its answer. It never types into a pane waiting on a prompt, and replies from you are marked verified
• Fleets: tuios fan starts one prompt in several agents, mixed harnesses allowed, each in its own git worktree. tuios start-agent starts one helper beside you, in its TUI or headless over ACP or the Codex app-server. Selectors such as group:fan/retry needs:you address a whole group
• Resume: After a daemon restart, the Inbox offers to resume each agent conversation that was running
• Pane Grants: Say what an agent's pane may do through tuios (read, write, fan, respond, admin), and give a helper less with --grants
• MCP Server: tuios mcp serves the same surface as MCP tools, read-only and held to the agent's own session unless you say otherwise
• tmux Shim: tuios tmux-shim runs tools that drive tmux, such as Claude Code agent teams, with their panes opened as tuios panes
• Session Stash: tuios stash put keeps a file for the session, so another agent can still open it
• Agent Skill: tuios --skill prints the short guide an agent in a pane reads to drive tuios, and tuios --skill TOPIC the rest, recipes included

Machines

• Hosts: tuios hosts add names another machine, reached over ssh. tuios hosts tailnet lists the machines on a Tailscale tailnet
• Remote Sessions: tuios attach --host build api draws a session on another machine in this client, and -s HOST:SESSION sends any command there
• Hosted Panes: tuios new-window NAME --host build runs one pane's process on another machine, in a session here
• Global Sessions: tuios new NAME --global holds panes from several machines (docs)
• Agents on Other Machines: tuios fan --host build and tuios start-agent -s build:api run agents there, their Inbox items show here, and tuios worktree pull brings their work back. Each machine's [hosts] policy says what the others may do

Tiling

• BSP Tiling: Binary Space Partitioning with spiral layout
• Scrolling Layout: niri-style columns on an infinite horizontal strip (docs)
• Master-Stack Layout: One master pane with the rest stacked beside it
• Smart Auto-Split: Aspect-ratio-aware splitting (opt-in)
• Shared Borders: tmux-style separator lines between panes (--shared-borders)
• Preselection: Control where the next pane spawns
• Equalize Splits: Reset all splits to balanced ratios

Scrollback & Copy Mode

• Vim-Style Copy Mode: Navigate 10,000-line scrollback with hjkl, search down with / and up with ?, yank with y
• Multi Copy Mode: Copy mode on every pane of the multifocus set at once. Search once, select with v/V in each pane, and yank all selections as plain text, markdown or JSON, to the clipboard or a file (docs)
• Mouse Wheel Scrollback: The wheel scrolls history with no mode entered; typing or reaching the bottom returns to live output
• Interactive Scrollbar: Click or drag the right border to jump to scroll position
• Selection Auto-Scroll: Drag selection above/below pane to scroll
• Scrollback Browser: OSC 133-aware command/output block navigation
• Scroll Position Indicator: Shows offset/total on the bottom border

Graphics & Protocols

• Kitty Graphics Protocol: Full image rendering with flicker-free video playback. mpv --vo=kitty works (both shm and base64), and youterm works.
• Sixel Graphics: Sixel image passthrough (experimental, no pixel-level clipping yet)
• Kitty Keyboard Protocol: Progressive enhancement (CSI u) with push/pop/query support. Fish 4.x compatible; Shift+printable bypasses the protocol and sends text directly.
• Synchronized Output: Mode 2026 prevents screen tearing
• Shared Memory Support: t=s passthrough for mpv --vo-kitty-use-shm
• Animation Frames: A guest's a=f frame edits are forwarded to the host, so a program that patches its own image cos