Welcome to TUIOS

TUIOS (Terminal UI Operating System) is a terminal-based window manager that brings modern window management to your terminal.

What is TUIOS?

Think of TUIOS as a tiling window manager for your terminal. Instead of managing GUI windows, you manage terminal sessions with:

• Modal Interface - Vim-inspired modes for window management and terminal interaction
• 9 Workspaces - Virtual desktops for organizing your terminal windows
• Automatic Tiling - Smart layouts that adapt as you create/close windows
• Command Palette - Quick access to all commands with Ctrl+P
• Pane Zoom - Temporarily fullscreen any pane with z (WM mode) or Prefix+z. Shared borders hidden when zoomed, dockbar shows Z indicator.
• Session Switcher - Browse and switch sessions in-app with Prefix+S
• Layout Templates - Save and load window arrangements for repeatable workflows
• Shared Borders - Compact tiling with --shared-borders for maximum screen space
• Vim Copy Mode - Navigate 10,000 lines of scrollback with vim motions
• Interactive Scrollbar - Click or drag the right border to scroll through history
• Mouse Wheel Scrollback - Scroll up with the mouse wheel to enter copy mode automatically
• Theming - 300+ built-in color themes
• SSH Server - Remote access with per-connection isolation
• Web Terminal - Browser access with WebGL rendering and WebTransport
• Graphics Support - Kitty graphics protocol with flicker-free video (mpv --vo=kitty and youterm work), sixel passthrough, and synchronized output
• Modern Protocols - Kitty keyboard protocol (CSI u), mode 2026/2027/2031, OSC 4/10-12/52/133
• Hooks System - Shell-command hooks for window/focus/workspace events
• Session Resurrection - Crash recovery via periodic state persistence
• Aggregate View - Browse all windows across 9 workspaces with fuzzy search
• Click-to-Open - Alt+Click file paths to open in $EDITOR
• Keyboard Multifocus - Type into multiple terminals simultaneously
• Cursor Shapes - Native vi-mode cursor rendering (block, bar, underline)
• Event-driven Rendering - Near-zero idle CPU usage; only redraws when state changes

Why TUIOS?

Problem: Switching between multiple terminal windows/tabs is cumbersome. You lose context, forget which terminal had what, and can't see everything at once.

Solution: TUIOS puts all your terminals in one view with:

• Split screen without tmux complexity
• Vim-like navigation (no mouse needed)
• Workspace organization (development, monitoring, testing)
• Scriptable automation with tape files

Quick Example

# Create 3 windows in a tiled layout
tuios
# Press 'n' to create window 1
# Press 'n' to create window 2
# Press 't' to enable tiling
# Press 'i' to enter terminal mode

Architecture

Built with Go 1.24+ using the Charm stack:

• Bubble Tea v2 - Event-driven TUI framework
• Lipgloss v2 - Terminal styling with caching
• Custom VT emulator - Full ANSI/VT100 support
• go-pty - Cross-platform PTY interface

Use Cases

Development Workflows

System Monitoring

Workspace 1: Development (editor, tests, git)
Workspace 2: Monitoring (htop, logs, metrics)
Workspace 3: Databases (psql, redis-cli)

SSH Sessions

# Start TUIOS SSH server
tuios ssh --host 0.0.0.0 --port 2222

# Connect remotely
ssh -p 2222 user@server

# Each connection gets isolated TUIOS session

Core Features Explained

Two Modes

Window Management Mode (default)

• Navigate between windows
• Create, close, rename windows
• Switch workspaces
• Tile layouts

Terminal Mode

• Send input to terminal
• Run commands
• Interact with applications
• Cycle windows with Alt+N/Alt+P (Linux/Windows) or Opt+Tab (macOS)

Press i to enter Terminal Mode. Exit with Alt+Esc, Ctrl+B then d, or Esc to return to Window Management.

9 Workspaces

Like virtual desktops, but for terminal windows:

• Alt+1-9 - Switch workspace
• Alt+Shift+1-9 - Move window to workspace

Each workspace remembers its layout and focused window.

Tiling Modes

Manual - Snap windows to positions (left, right, fullscreen, corners)

Automatic - Grid-based tiling that adapts as you add/remove windows

Press t to toggle tiling mode.

Copy Mode

Access scrollback with vim motions:

• Ctrl+B [ - Enter copy mode
• hjkl - Navigate
• / - Search forward
• v - Visual selection
• y - Copy to clipboard

Navigate 10,000 lines of history per window.

Documentation Overview

Terminal Features

Cursor Shape Support

TUIOS supports native cursor shape rendering for applications that request different cursor styles:

• Block cursor - Default cursor style
• Bar cursor - Thin vertical line (common in insert mode)
• Underline cursor - Horizontal line under text
• Blink support - Respects application requests for blinking/steady cursor

This is particularly useful for vi-mode users in shells like zsh (with zsh-vi-mode plugin) where the cursor changes based on the editing mode.

Graphics Support (Experimental)

TUIOS supports the Kitty graphics protocol and Sixel graphics for inline image display. Applications running inside TUIOS can display images directly in the terminal when using a compatible host terminal.

Supported host terminals:

• Kitty
• WezTerm
• Ghostty
• iTerm2 (partial)
• Foot
• Contour

Kitty graphics features:

• Raw image passthrough from guest to host terminal (no re-encoding)
• Flicker-free video via image ID reuse
• Shared memory support (t=s for mpv)
• File path forwarding (t=f)
• Viewport clipping and scroll handling
• Mode 2026 synchronized output wrapping
• Animation protocol (a=f, a=a, a=c) not supported due to ID remapping constraints

Sixel graphics (experimental):

• Raw sixel data passthrough
• Window boundary awareness (hides images that overflow)
• Pixel-level clipping not yet implemented (images that don't fit are hidden)

Terminal Protocol Support

TUIOS implements modern terminal protocols for application compatibility:

• Kitty keyboard protocol - Progressive enhancement via CSI u encoding. Applications can push/pop keyboard flags for disambiguated key reporting. Fish 4.x compatible; Shift+printable bypasses the protocol and sends text directly.
• Mode 2026 (synchronized output) - Tracked in the VT emulator for flicker-free rendering.
• Mode 2027 (unicode core) - Width calculation method selection.
• OSC 4 - Indexed color palette query/set.
• OSC 10-12 - Default foreground/background/cursor color query/set.
• OSC 52 - Clipboard operations.
• OSC 133 - Shell integration / semantic zones for scrollback navigation.
• CSI 14t/16t/18t - Terminal and cell size reporting.
• OSC 66 - Kitty text sizing protocol (experimental - basic passthrough works but has known issues with scrollback and window repositioning).

See the Architecture page for technical details.

Community & Support

• GitHub: Gaurav-Gosain/tuios
• Issues: Report bugs and request features
• Discussions: Ask questions and share workflows
• License: MIT - Free and open source