TUIOS v0.5.0 - Major Release

Released: December 25, 2025
Documentation: https://tuios.gaurav.zip

Note: Throughout this document, Ctrl+B refers to the default leader key. This is configurable via the leader_key option in your config file. See CONFIGURATION.md for details.

Highlights

TUIOS v0.5.0 is the biggest release yet, adding persistent sessions with daemon mode, multi-client collaboration, and comprehensive remote control capabilities.

Three Major Features

1. Persistent Sessions

persistent-sessions.mp4

Sessions now survive disconnects and crashes with automatic daemon management. The daemon starts in-process when you create or attach to a session.

# Create a persistent session
tuios new work-session

# Detach (Ctrl+B d) and come back later
tuios ls
tuios attach work-session

Full state preservation: windows, layouts, BSP trees, terminal content, scrollback history. Sessions persist as long as the daemon process is running.

2. Multi-Client Support

multi-client.mp4

Multiple users can attach to the same session simultaneously with real-time state synchronization. Perfect for pair programming and remote troubleshooting.

# Terminal 1
laptop$ tuios new pairing

# Terminal 2 (different machine)
remote$ tuios attach pairing

# Or via SSH using username as session name
remote$ ssh -p 2222 pairing@yourserver

Both clients see the same session in real-time with synchronized focus, mode changes, and terminal output.

SSH Integration: Connect to sessions directly via SSH username:

ssh -p 2222 mysession@localhost - Attach to "mysession"
Session picker appears if no session specified

See MULTI_CLIENT.md for complete guide.

3. Remote Control CLI

remote-commands.mp4

Comprehensive automation and scripting capabilities. Control TUIOS from external scripts without attaching a TUI.

# Send keystrokes
tuios send-keys "ctrl+b n"

# Execute commands
tuios run-command NewWindow "build-server"

# Change configuration at runtime
tuios set-config dockbar_position top

# Execute tape scripts remotely
tuios tape exec deploy.tape

# Inspect state without TUI
tuios list-windows --json
tuios session-info

12+ remote commands with full shell completion support.

New Features

BSP Tiling Enhancements

bsp.mp4

Advanced manual control for precise layouts:

Preselection: Ctrl+B Shift+H/J/K/L - Control where next window spawns
Manual splits: Ctrl+B - (horizontal), Ctrl+B | (vertical)
Split rotation: Ctrl+B R - Rotate split direction
Equalize splits: Ctrl+B = - Reset to 50/50 ratios
Edge-based resizing: >, <, ., ,, }, {, ], [

BSP layouts are serialized and restored in daemon mode.

See BSP_TILING.md for workflows and examples.

Mouse Edge Snapping

Drag windows to screen edges for intuitive snapping:

Top center → Fullscreen
Left/Right edge → Half screen
Corners → Quarter screen
Works in floating window mode for window swapping

Tape Recording

Live session recording with keybindings:

Ctrl+B T r  # Start recording
Ctrl+B T s  # Stop recording
Ctrl+B T p  # Pause/Resume

tuios tape list
tuios tape play recording.tape

See TAPE_RECORDING.md for complete guide.

Library Export

Use TUIOS as an importable Go library:

import "github.com/Gaurav-Gosain/tuios/pkg/tuios"

app := tuios.New(
    tuios.WithTheme("dracula"),
    tuios.WithAnimations(false),
    tuios.WithShell("/bin/fish"),
)

See LIBRARY.md for API documentation.

Native Windows Support

Full daemon mode support on Windows 10+ (build 17063+) with ConPTY.

Showkeys Overlay

Display pressed keys on-screen for presentations and screencasts:

tuios --show-keys
# Or toggle in session: Ctrl+B D k

See SHOWKEYS.md for configuration options.

Window Customization

New appearance options:

window_title_position - bottom, top, or hidden
hide_clock - Hide clock overlay
--no-animations - Instant transitions for tape playback

Bug Fixes

Critical Race Conditions

Fixed multiple critical data races:

Client.Close() double-close protection with sync.Once
Window suppressCallbacks converted to atomic.Bool
Daemon goroutine lifecycle management with sync.WaitGroup
5-second graceful shutdown timeout

All tests now pass with race detector.

VT Emulator

Drain VT responses to prevent escape sequence leaks
Proper VT response forwarding in daemon mode
Nil color panic prevention (synced from upstream)
Graceful write-after-close handling

Platform-Specific

Fixed macOS keybind mapping (opt+ vs alt+)
Fixed daemon mode window sizing on reattach
Fixed BSP tree persistence on window swap

Architecture Changes

Charm.land Migration

Migrated from github.com/charmbracelet to charm.land packages:

Bubble Tea v2.0.0-rc.2
Lipgloss v2.0.0-beta.3
Wish v2.0.0
Sip v0.1.11

Updated API compatibility for new package versions.

Code Organization

CLI Modularization: Split main.go into 7 focused modules for better maintainability.

Render Splitting: Split render.go into 5 specialized modules (dock, overlays, terminal, helpers).

New Session Package: Added internal/session/ for daemon, client, protocol, and state management.

VT Emulator Sync: Updated deprecated constants, simplified grapheme width calculation.

Documentation

New Guides

BSP_TILING.md - Complete BSP guide with practical workflows
TAPE_RECORDING.md - Session recording and playback
SHOWKEYS.md - Overlay configuration for presentations
LIBRARY.md - Go library usage and API reference
MULTI_CLIENT.md - Multi-client collaboration guide

Updated Documentation

CLI_REFERENCE.md - Complete remote control command reference
ARCHITECTURE.md - Multi-client architecture diagrams
KEYBINDINGS.md - New BSP and recording keybinds
CONFIGURATION.md - New appearance options
README.md - Expanded feature overview

Testing

Added comprehensive test coverage:

Session management tests (protocol, multi-client scenarios)
BSP tree manipulation tests
Tape executor tests
Memory pool tests
Theme and config tests
Concurrency and race condition tests

All tests pass with race detector. Zero staticcheck warnings.

Remote Control Reference

Understanding --literal and --raw

The send-keys command has two important flags that control how keys are processed:

Without any flags (default mode):

Keys are sent to TUIOS itself (for window management, mode switching, etc.)
Both spaces and commas split the input into separate key arguments
Examples:
- tuios send-keys "ctrl+b n" → Sends Ctrl+B, then n (two keys)
- tuios send-keys "ctrl+b,n" → Same as above (comma splits)
- tuios send-keys "a b c" → Sends a, then b, then c (space splits)

--literal flag:

Keys are sent directly to the terminal PTY (bypass TUIOS key handling)
Still splits on spaces and commas by default
Example: tuios send-keys --literal "echo hello" → Sends "echo", then "hello" (WRONG!)

--raw flag:

Treats each character as a separate key
NO splitting on spaces or commas
Each character becomes its own key press
Example: tuios send-keys --raw "hello world" → Sends h, e, l, l, o, space, w, o, r, l, d

Combining --literal and --raw (for typing text in terminal):

# Correct way to type text with spaces in the terminal
tuios send-keys --literal --raw "echo hello world"

# This sends each character to the PTY, including spaces

Common Patterns:

# Send TUIOS commands (window management)
tuios send-keys "ctrl+b n"                    # Create new window
tuios send-keys "ctrl+b,t"                    # Toggle tiling (comma separator)
tuios send-keys "\$PREFIX q"                  # Quit (using PREFIX token)

# Send keys to terminal
tuios send-keys --literal --raw "ls -la"      # Type command in terminal
tuios send-keys --literal --raw "cd /tmp"     # Change directory

# Raw mode for text with spaces (without literal, goes to TUIOS)
tuios send-keys --raw "some text"             # Each character as separate key to TUIOS

Special Keys:

Enter, Return, Space, Tab, Escape, Esc
Backspace, Delete
Up, Down, Left, Right, Home, End
PageUp, PageDown, F1-F12

Modifiers:

ctrl, alt, opt, shift, super, meta

Available Commands

# Keystroke control
tuios send-keys <keys> [--literal] [--raw] [-s session]

# Command execution
tuios run-command <command> [args...] [--json] [-s session]

# Configuration
tuios set-config <path> <value> [-s session]

# Tape automation
tuios tape exec <file.tape> [-s session]

# Inspection (no TUI required)
tuios list-windows [--json] [-s session]
tuios get-window [id-or-name] [--json] [-s session]
tuios session-info [--json] [-s session]

# Debug
tuios logs [-s session]

Full shell completion available for all commands.

Upgrade Notes

For End Users

Sessions now persist as long as daemon is running (daemon starts automatically)
Use tuios ls to see all sessions
Try new remote commands: tuios send-keys, tuios run-command
Explore BSP enhancements with preselection and manual splits
Try SSH multi-client: ssh -p 2222 sessionname@yourserver

For Developers

Update import paths: github.com/charmbracelet → charm.land
tea.PasteMsg is now a struct with .Content field
Use pkg/tuios library API for embedding TUIOS

Breaking Changes

Import paths changed to charm.land packages
Session state format changed (pre-v0.5.0 sessions won't persist)

Installation

# macOS (Homebrew)
brew install tuios

# Linux (from source)
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest

# Or download pre-built binaries from releases

What's Next

Future roadmap ideas:

Persistent daemon with system service support
Authentication for web terminal
Session monitoring and analytics
Custom theme editor
Plugin system

Changelog Summary

Added:

Persistent sessions with daemon mode
Multi-client real-time collaboration
SSH username-based session attachment
Remote control CLI (12+ commands)
BSP tiling enhancements (preselection, manual splits, rotation)
Mouse edge snapping
Tape recording with live keybindings
Library export (pkg/tuios)
Native Windows support
Showkeys overlay (Ctrl+B D k)
Window customization options

Changed:

Migrated to charm.land packages (Bubble Tea v2 RC2, Lipgloss v2, Wish v2)
Modularized CLI and rendering code
Synced VT emulator with upstream

Fixed:

Critical race conditions in client/daemon/window
VT emulator escape sequence handling
Platform-specific issues (macOS keybinds, Windows daemon)
Documentation issues (send-keys examples, daemon commands)

Security:

Thread-safe multi-client channels
Proper goroutine lifecycle management
Unix socket permissions (0700)

Full Details: https://github.com/Gaurav-Gosain/tuios/releases/tag/v0.5.0
Documentation: https://tuios.gaurav.zip

Happy Holidays!

Changelog

New Features

b2c98d9: feat: add --no-animations flag to tuios-web and expose tuios as importable library (@Gaurav-Gosain)
93d6244: feat: add multi-client state sync with thread-safe channel communication (@Gaurav-Gosain)
9822600: feat: add native Windows support for daemon mode and modularize CLI (@Gaurav-Gosain)
a670bdb: feat: add remote control CLI, mouse edge snapping, and window customization (@Gaurav-Gosain)
e895e0a: feat: add thread-safe ClientEventChan for multi-client notifications (@Gaurav-Gosain)

Bug Fixes

0697323: fix: daemon mode reattach window sizing in tiling mode (@Gaurav-Gosain)
906602c: fix: drain VT emulator responses to prevent escape sequence leaks (@Gaurav-Gosain)
46e39f8: fix: fix bug with macos not setting opt+ keybinds instead of alt+ for some config options (@Gaurav-Gosain)
16a080b: fix: forward daemon VT responses while draining client responses (@Gaurav-Gosain)
282cb18: fix: resolve critical race conditions in client, daemon, and window (@Gaurav-Gosain)
22bf3a3: fix: resolve lint warnings and add comprehensive test coverage (@Gaurav-Gosain)
9dba0c9: fix: simplify session CLI by removing redundant flags (@Gaurav-Gosain)

Other Changes

cba0c5a: refactor: comprehensive codebase cleanup and upstream VT sync (@Gaurav-Gosain)
c1c6e01: refactor: migrate from github.com/charmbracelet to charm.land packages (@Gaurav-Gosain)

Full Changelog: v0.4.4...v0.5.0

Gaurav-Gosain/tuios v0.5.0 on GitHub

TUIOS v0.5.0 - Major Release

Highlights

Three Major Features

New Features

BSP Tiling Enhancements

Mouse Edge Snapping

Tape Recording

Library Export

Native Windows Support

Showkeys Overlay

Window Customization

Bug Fixes

Critical Race Conditions

VT Emulator

Platform-Specific

Architecture Changes

Charm.land Migration

Code Organization

Documentation

New Guides

Updated Documentation

Testing

Remote Control Reference

Understanding --literal and --raw

Available Commands

Upgrade Notes

For End Users

For Developers

Breaking Changes

Installation

What's Next

Changelog Summary

Changelog

New Features

Bug Fixes

Other Changes

Gaurav-Gosain/tuios v0.5.0
on GitHub