TUIOS is a terminal-based window manager that provides a modern, efficient interface for managing multiple terminal sessions. Built with Go using the Charm stack (Bubble Tea v2 and Lipgloss v2), TUIOS offers a vim-like modal interface with comprehensive keyboard shortcuts, workspace support, and mouse interaction.
- Keybindings Reference - Complete keyboard shortcut reference
- Configuration Guide - Customize keybindings and settings
- CLI Reference - Command-line options and flags
- Web Terminal - Browser-based terminal access
- Architecture Guide - Technical architecture and design
Table of Contents
Homebrew (macOS/Linux):
# TUIOS terminal window manager
brew install tuios
# tuios-web (separate binary for web terminal server)
brew install tuios-webArch Linux (AUR):
# TUIOS terminal window manager
yay -S tuios-bin
# tuios-web (separate binary for web terminal server)
yay -S tuios-web-binNix:
# Run directly
nix run github:Gaurav-Gosain/tuios#tuios
# Or add to your configuration
nix-shell -p tuiosLinux/macOS:
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bashAlternative Methods:
- GitHub Releases - Download pre-built binaries for both
tuiosandtuios-web - Go Install:
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest(main binary)go install github.com/Gaurav-Gosain/tuios/cmd/tuios-web@latest(web server)
- Docker:
docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest - Build from Source: See Development section below
Requirements:
- A terminal with true color support (most modern terminals)
- Go 1.24+ (if building from source)
- Multiple Terminal Windows: Create and manage multiple terminal sessions
- 9 Workspaces: Organize windows across independent workspaces
- Modal Interface: Vim-inspired Window Management and Terminal modes
- Automatic Tiling: Optional grid-based window layouts
- Vim-Style Copy Mode: Navigate scrollback (10,000 lines), search, and select text with vim keybindings
- Customizable Keybindings: TOML configuration file with full keybinding customization (Kitty protocol support)
- Mouse Support: Click, drag, and resize with full mouse interaction
- SSH Server Mode: Remote terminal multiplexing with per-connection isolation
- Web Terminal Mode: Access TUIOS from any browser with WebGL rendering
- Smart Performance: Style caching, viewport culling, adaptive refresh (60Hz/30Hz)
Launch TUIOS:
tuiosEssential Keys:
Window Management Mode (default):
- n - Create new window
- i or Enter - Enter Terminal Mode
Works from any mode:
- Ctrl + B c - Create new window
- Ctrl + B ? - Toggle help overlay
- Ctrl + B [ - Enter copy mode (vim-style scrollback)
- Ctrl + B d or Esc - Return to Window Management Mode
- Ctrl + B q - Quit
Alternative (Ctrl + B t submenu):
- Ctrl + B t n - Create new window
- Ctrl + B t x - Close window
- Ctrl + B t r - Rename window
SSH Server Mode:
tuios ssh # Start on localhost:2222
tuios ssh --host 0.0.0.0 --port 8022 # Custom host/port
ssh -p 2222 localhost # ConnectWeb Terminal Mode (requires separate tuios-web binary):
tuios-web # Start on http://localhost:7681
tuios-web --port 8080 # Custom port
tuios-web --theme dracula # With theme
open http://localhost:7681 # Open in browserFeatures: WebGL rendering, WebTransport/WebSocket, bundled Nerd Fonts, settings panel.
Install tuios-web:
# Homebrew
brew install tuios-web
# AUR
yay -S tuios-web-bin
# Go install
go install github.com/Gaurav-Gosain/tuios/cmd/tuios-web@latestTape Scripting (Automation):
# Run tape script in headless mode (background)
tuios tape run examples/demo.tape
# Run tape script with visible TUI (watch automation)
tuios tape play examples/demo.tape
# Validate tape file syntax
tuios tape validate examples/demo.tapeConfiguration:
tuios config edit # Edit keybindings in $EDITOR
tuios config path # Print config file location
tuios config reset # Reset to defaults
tuios keybinds list # View all current keybindings
tuios keybinds list-custom # View only your customizationsShell Completions:
# Bash
tuios completion bash > /etc/bash_completion.d/tuios
# Zsh
tuios completion zsh > "${fpath[1]}/_tuios"
# Fish
tuios completion fish > ~/.config/fish/completions/tuios.fish
# PowerShell
tuios completion powershell > tuios.ps1For complete keybindings, configuration options, and CLI flags, see the Documentation section above.
TUIOS supports automation through .tape files - a simple, declarative format for automating interactions. Perfect for:
- Recording and replaying terminal workflows
- Automated testing
- Demo recording
- CI/CD automation
- Terminal workflow documentation
- Setup of development environments
Basic Tape File Syntax:
# Create windows and windows
NewWindow
Sleep 500ms
# Type text with delays
Type "echo 'Hello, TUIOS!'"
Enter
# Key presses and combinations
Ctrl+B
Type "n"
# Navigation and window management
SwitchWorkspace 2
Sleep 1s
# Sleep between commands
Sleep 500ms
Supported Commands:
Type "text"- Type textType@100ms "text"- Type with custom speedEnter,Space,Tab,Escape- Special keysBackspace,Delete- Editing keysUp,Down,Left,Right- NavigationCtrl+X,Alt+X,Shift+X- Key combinationsSleep 500msorSleep 2s- DelaysNewWindow,CloseWindow,ToggleTiling- Window managementSwitchWorkspace N- Switch to workspaceMoveToWorkspace N- Move window to workspaceFocus,Split- Window manipulation
Running Tape Scripts:
# Headless mode (background) - useful for automation
tuios tape run script.tape
# Interactive mode (visible TUI) - watch it happen
tuios tape play script.tape
# Validate syntax
tuios tape validate script.tapeExample Tapes:
examples/simple.tape- Basic tape fileexamples/demo.tape- Comprehensive demoexamples/advanced.tape- Complex scenarios
TUIOS is built on the Bubble Tea v2 framework following the Model-View-Update pattern. For detailed architecture diagrams and technical documentation, see Architecture Guide.
Key Technologies:
- Bubble Tea v2 - Event-driven TUI framework
- Lipgloss v2 - Terminal styling
- go-pty - Cross-platform PTY interface
- Wish v2 - SSH server
- Vendored VT - ANSI/VT100 terminal emulator
Core Components:
- Window Manager (
internal/app/os.go) - Central state and workspace orchestration - Terminal Emulation (
internal/vt/) - ANSI parser with 10,000 line scrollback - Rendering Engine (
internal/app/render.go) - Layer composition with viewport culling - Input System (
internal/input/) - Modal routing and 100+ configurable keybindings - Configuration (
internal/config/) - TOML-based keybinding customization
Optimization Strategies:
- Smart caching with sequence-based change detection
- Viewport culling for off-screen windows
- Adaptive refresh rates (60Hz focused, 30Hz background)
- Memory pooling for strings, buffers, and styles
- LRU style cache (40-60% allocation reduction)
- Frame skipping when no changes detected
Common Issues:
- Colors not displaying: Set
COLORTERM=truecolorenvironment variable - SSH connection issues: Use
--host 0.0.0.0for remote access, check firewall settings - Performance with many windows: Enable tiling mode (t key)
Debug Mode: Press Ctrl + L to view system logs.
Completed:
- ✓ Multiple windows with 9 workspaces
- ✓ Automatic tiling and snapping
- ✓ Vim-style copy mode with search
- ✓ SSH server mode
- ✓ Performance optimizations
- ✓ TOML configuration system with custom keybindings
Planned:
- Theme and color customization
- Session persistence
- Split panes and tabs
- Plugin system
Contributions are welcome! Feel free to open issues or pull requests.
Build from Source:
git clone https://github.com/gaurav-gosain/tuios.git
cd tuios
go build -o tuios ./cmd/tuios
./tuiosRun Tests:
go test ./...Support:
This project is licensed under the MIT License - see the LICENSE file for details.
- The Charm team for Bubble Tea and Lipgloss libraries
- The Go terminal ecosystem for PTY and VT implementations
- The vim and tmux communities for interface design inspiration
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
