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
• Vim Copy Mode - Navigate 10,000 lines of scrollback with vim motions
• 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 for inline image display (experimental)
• Cursor Shapes - Native vi-mode cursor rendering (block, bar, underline)

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 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

Features:

• Image passthrough from guest to host terminal
• Automatic capability detection
• Multi-window image support
• Viewport clipping and scroll handling

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