(⌐■_■) TUIOS is an experimental terminal tiling multiplexer

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.

• Installation
• Features
• Usage
  • Keyboard Shortcuts
  • Mouse Controls
• Configuration
• Architecture
• Performance
• Troubleshooting
• Dependencies
• Roadmap
• Development
  • Local Development
  • Creating Releases
• Contribution
• License

You can install TUIOS using one of the following methods:

Install the latest release with a single command:

Or if you prefer to inspect the script first:

The script will automatically:

• Detect your OS and architecture
• Download the appropriate binary from the latest release
• Install it to /usr/local/bin (or ~/bin if no sudo access)
• Verify the installation

Grab the latest release from the releases page and extract the archive to a location of your choice.

You can also install TUIOS using the go install command:

You can pull the latest docker image from the GitHub Docker Container Registry and run it using the following command:

If you prefer to build from source, follow these steps:

1. Clone the repository:

   git clone https://github.com/gaurav-gosain/tuios.git

2. Navigate to the project directory:

3. Build the executable:

   go build -o tuios ./cmd/tuios

4. Run TUIOS:

   Or check the version:

• Go 1.24 or later (for building from source or using go install)
• A terminal with true color support (most modern terminals)

TUIOS uses the following libraries:

• Bubble Tea v2: Terminal UI framework
• Lipgloss v2: Terminal styling library
• Charm VT: Virtual terminal emulator
• go-pty: Cross-platform PTY interface
• Wish v2: SSH server library

• Multiple Terminal Windows: Create and manage multiple terminal sessions simultaneously
• Workspace Support: Organize windows across 9 independent workspaces
• Modal Interface: Vim-inspired design with Window Management Mode and Terminal Mode
• Automatic Tiling: Optional automatic window tiling with intelligent layouts
• Window Minimization: Minimize windows to dock with smooth animations
• Real-time Updates: 60Hz polling for responsive terminal content updates
• Mouse Support: Full mouse interaction for window management, dragging, and resizing

• Dynamic Layouts: Snap windows to screen edges, corners, or fullscreen
• Workspace Organization: 9 workspaces for organizing terminal sessions
• Tiling Mode: Automatic window arrangement with grid-based layouts
• Drag and Drop: Move windows by dragging with mouse (with tiling swap support)
• Resize Support: Right-click and drag to resize windows (disabled in tiling mode)
• Window Minimization: Minimize to dock with pill-style indicators
• Z-index Management: Automatic window layering and focus management
• Visual Feedback: Clear border colors indicating focus state and mode

• Tmux-style Prefix Mode: Ctrl+B prefix for advanced commands
• Window Renaming: Custom names for easy identification
• Smart Animations: Smooth transitions for minimize/restore/snap operations
• CPU Monitoring: Real-time CPU usage graph in status bar
• Comprehensive Help System: Built-in contextual help overlay
• Text Selection & Copying: Mouse and keyboard-based text selection with clipboard integration
• Smart Notifications: Responsive notification system with overflow protection
• SSH Server Mode: Run TUIOS as SSH server for remote terminal multiplexing
• Session Isolation: Each SSH connection gets dedicated TUIOS instance

Local Mode (Default)

Launch TUIOS from your terminal:

The application starts with a welcome screen. Press n to create your first terminal window.

SSH Server Mode

Run TUIOS as an SSH server to allow remote connections:

Each SSH connection gets its own isolated TUIOS instance with full terminal multiplexer capabilities.

Flag Description Default

--ssh	Run as SSH server	false
--port	SSH server port	2222
--host	SSH server host	localhost
--key-path	SSH host key path	Auto-generated

Key Action

n	Create new window
x	Close current window
r	Rename window
m	Minimize window
Shift+M	Restore all minimized windows
Tab	Focus next window
Shift+Tab	Focus previous window
1-9	Select window by number (in tiling mode)

Key Action

Alt+1-9	Switch to workspace 1-9
Alt+Shift+1-9	Move window to workspace and follow
Ctrl+B, w, 1-9	Switch to workspace (prefix alternative)
Ctrl+B, w, Shift+1-9	Move window to workspace (prefix alternative)

Key Action

h	Snap window to left half
l	Snap window to right half
f	Fullscreen window
u	Unsnap/restore window
1-4	Snap to corner (1=top-left, 2=top-right, 3=bottom-left, 4=bottom-right)

Key Action

t	Toggle automatic tiling
Shift+H / Ctrl+←	Swap with window to the left
Shift+L / Ctrl+→	Swap with window to the right
Shift+K / Ctrl+↑	Swap with window above
Shift+J / Ctrl+↓	Swap with window below

Key Action

i, Enter	Enter Terminal Mode
Esc	Exit Terminal Mode
?	Toggle help overlay
q, Ctrl+C	Quit application

Key Action

s	Toggle selection mode
Ctrl+S	Toggle selection mode from terminal mode
Mouse drag	Select text (mouse-based)
Arrow keys	Move cursor in selection mode
Shift+Arrow keys	Extend selection
c	Copy selected text to clipboard
Ctrl+V	Paste from clipboard (works in terminal mode)
Esc	Clear current selection

Key Action

Ctrl+↑/↓	Swap windows or maximize/unsnap

Key Action

Ctrl+L	Toggle log viewer

Similar to tmux, TUIOS supports a prefix key for advanced commands. Press Ctrl+B, release, then press the command key:

Key Sequence Action

Ctrl+B c	Create new window
Ctrl+B x	Close current window
Ctrl+B , / r	Rename window
Ctrl+B n / Tab	Next window
Ctrl+B p / Shift+Tab	Previous window
Ctrl+B 0-9	Jump to window
Ctrl+B Space	Toggle tiling mode
Ctrl+B w 1-9	Switch to workspace (universal alternative)
Ctrl+B w Shift+1-9	Move window to workspace
Ctrl+B m m	Minimize focused window
Ctrl+B m 1-9	Restore minimized window by number
Ctrl+B m Shift+M	Restore all minimized windows
Ctrl+B t ...	Window prefix (see below)
Ctrl+B d	Detach from terminal (exit terminal mode)
Ctrl+B s	Toggle selection mode
Ctrl+B Ctrl+B	Send literal Ctrl+B to terminal

For users who prefer prefix-based controls matching normal mode keybinds, the window prefix provides an alternative way to access common window management commands:

Key Sequence Action

Ctrl+B t n	Create new window
Ctrl+B t x	Close window
Ctrl+B t r	Rename window
Ctrl+B t Tab	Next window
Ctrl+B t Shift+Tab	Previous window
Ctrl+B t t	Toggle tiling mode

• Left Click: Focus window
• Left Drag: Move window (swap in tiling mode) or select text (in selection mode)
• Right Drag: Resize window (disabled in tiling mode)
• Window Controls: Click minimize, maximize, or close buttons in title bar
• Dock Click: Click minimized windows in dock to restore

The bottom status bar displays:

• Mode Indicator: [W] for Window Mode, [T] for Terminal Mode, [T] for Tiling
• Workspace Indicator: Shows current workspace and windows per workspace
• Minimized Windows: Pill-style dock items with custom names
• CPU Graph: Real-time CPU usage visualization

TUIOS uses sensible defaults but can be customized through code constants:

• Window Defaults: 20x5 characters for new windows
• Animation Speed: 300ms standard duration
• Refresh Rate: 60 FPS normal, 30 FPS during interactions
• Buffer Sizes: 100 log messages, efficient terminal rendering

Component Technology Purpose

UI Framework	Bubble Tea v2	Event-driven terminal UI
Styling	Lipgloss v2	Terminal styling and layouts
Terminal Emulation	VT	Virtual terminal implementation
Process Management	PTY	Pseudo-terminal interface
Concurrency	Go Routines	Parallel I/O and event handling

1. Window Manager (os.go)

   • Workspace management
   • Window lifecycle
   • Focus handling
   • Event dispatching

2. Terminal Windows (window.go)

   • Process spawning
   • I/O multiplexing
   • Scrollback buffer
   • Content caching

3. Input System (input.go)

   • Modal keyboard handling
   • Mouse event processing
   • Prefix command parsing
   • Shortcut management

4. Rendering Engine (render.go)

   • Layer composition
   • Efficient redrawing
   • Animation frames
   • UI element styling

5. Layout System (tiling.go)

   • Automatic tiling
   • Window snapping
   • Grid calculations
   • Swap operations

• Smart Caching: Terminal content cached with sequence-based change detection
• Enhanced Viewport Culling: Aggressive off-screen window culling with animation-aware margins
• Adaptive Refresh: Dynamic FPS based on activity (60Hz normal, 30Hz during interactions)
• Expanded Memory Pooling: Object pools for strings, byte buffers, layers, and styles
• Intelligent Updates: Background windows throttled to ~20Hz vs 60Hz for focused windows
• Throttled Background Updates: Focused windows update at 60Hz, background windows at ~20Hz
• Frame Skipping: Skip rendering when no changes and no active animations

Operation Performance

Window Creation	< 50ms
Window Switch	< 1ms
Workspace Switch	< 5ms
Full Render	< 16ms (60 FPS)

Window not closing with exit/Ctrl+D

• Fixed with improved process exit detection and context-based goroutine cleanup
• Windows now properly detect shell termination and clean up resources

Performance issues with many windows

• Enable tiling mode for better performance
• Background windows automatically throttle updates to ~20Hz
• Enhanced memory pooling reduces allocation overhead
• Smart caching prevents unnecessary terminal re-renders

Resource leaks or high memory usage

• Fixed with proper goroutine lifecycle management using context cancellation
• Enhanced I/O operation cleanup prevents hanging processes
• Object pooling reduces garbage collection pressure

Mouse not working

• Ensure your terminal supports mouse events
• Try running with --mouse flag if available

Colors not displaying correctly

• Verify terminal supports true color (24-bit)
• Set COLORTERM=truecolor environment variable

Text selection not working

• Ensure you're in selection mode (press s first)
• Use mouse drag or arrow keys to select text
• Text remains highlighted until copied or cleared with Escape

Clipboard copying fails

• Ensure your system has clipboard support
• Try alternative copy method if primary clipboard isn't available
• Selected text must be highlighted before copying with c

SSH connection issues

• Ensure TUIOS SSH server is running: ./tuios --ssh
• Check firewall settings allow connections on the specified port
• SSH host key will be auto-generated on first run in ~/.ssh/tuios_host_key
• For remote access, use --host 0.0.0.0 to bind to all interfaces

SSH authentication problems

• TUIOS SSH server accepts any SSH connection (no authentication required)
• This is intended for development/local use - add authentication for production
• SSH keys are handled by the client's SSH configuration

Press Ctrl+L to open the log viewer and see system messages.

TUIOS relies on the following third-party packages:

• bubbletea: A powerful little TUI framework
• lipgloss: Style definitions for nice terminal layouts
• x/vt: Virtual terminal emulator
• pty: PTY interface for Go
• wish: Make SSH apps, just like that!

The following features are planned for future implementation:

• Multiple terminal windows with tab support
• Workspace management across 9 workspaces
• Window tiling and snapping functionality
• Mouse support for window management
• SSH server mode for remote multiplexing
• Text selection and clipboard integration
• Scrollback Buffers: Terminal history and scrolling
  • Mouse scroll wheel support for terminal content
  • Keyboard shortcuts for scrolling (Page Up/Down, Ctrl+U/D)
  • Configurable scrollback buffer size
  • Search within scrollback history
• Enhanced Text Selection: Improve selection capabilities
  • Word and line selection modes (double-click, triple-click)
  • Block/column selection mode
  • Search and select functionality
  • Copy with formatting preservation

• Configuration System: User-configurable settings
  • Custom key bindings
  • Theme and color customization
  • Performance tuning options
  • Configuration file support (YAML/TOML)
• Session Management: Save and restore terminal sessions
  • Workspace layouts persistence
  • Window state restoration
  • Custom session profiles
• Advanced Terminal Features:
  • Split panes within windows
  • Terminal tabs within windows
  • Background/foreground job management
  • Terminal bell notifications

• Plugin System: Support for user extensions and customizations
  • Custom status bar widgets
  • Theme plugins
  • Custom layout algorithms
• Advanced SSH Features:
  • User authentication and authorization
  • Session sharing and collaboration
  • SSH tunneling support
• Performance Monitoring:
  • Memory usage graphs
  • Network I/O monitoring
  • Disk usage visualization
• Accessibility Features:
  • Screen reader support
  • High contrast themes
  • Keyboard navigation improvements

You can also run TUIOS locally using docker:

1. Clone the repository:

   git clone https://github.com/gaurav-gosain/tuios.git

2. Navigate to the project directory:

3. Build the docker image:

4. Run the docker image:

For building from source, refer to the Build from Source section in the Installation guide above.

Contributions are welcome! Whether you want to add new features, fix bugs, or improve documentation, feel free to open a pull request.

TUIOS uses GoReleaser for automated releases. To create a new release:

1. Tag the commit with a semantic version:

   git tag -a v1.0.0 -m "Release v1.0.0"

2. Push the tag to trigger the release workflow:

The GitHub Actions workflow will automatically:

• Build binaries for multiple platforms (Linux, macOS, Windows, FreeBSD, OpenBSD)
• Create archives with checksums
• Generate a changelog
• Publish the release to GitHub

You can test the release configuration locally (requires goreleaser installed):

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