Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Gaurav-Gosain/tuios/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

TUIOS provides 9 independent workspaces for organizing your terminal windows. Think of workspaces as virtual desktops - each one can contain multiple windows with their own layout, and you can quickly switch between them. Workspaces are perfect for:
  • Separating different projects or contexts
  • Organizing development, monitoring, and operations tasks
  • Creating dedicated environments for specific workflows
  • Reducing clutter by grouping related windows together

​
Switching Workspaces

​
Quick Switch

The fastest way to switch workspaces is using keyboard shortcuts: 
# Switch to workspace 1-9
Alt+1  # Workspace 1
Alt+2  # Workspace 2
Alt+3  # Workspace 3
# ... and so on through Alt+9
On macOS, the Option key (⌥) is used instead of Alt. The default configuration automatically handles this platform difference.

​
Prefix-Based Switching

Alternatively, use the prefix key followed by workspace menu: 
# Using prefix key (Ctrl+B by default)
Ctrl+B w 1    # Switch to workspace 1
Ctrl+B w 2    # Switch to workspace 2
# ... etc

​
CLI Remote Control

Switch workspaces from the command line using remote control: 
# Switch to workspace 2 in running session
tuios run-command SwitchWorkspace 2

# Switch in a specific session
tuios run-command -s mysession SwitchWorkspace 3

​
Moving Windows Between Workspaces

​
Move and Follow

The most common operation is to move the focused window to another workspace and switch to that workspace: 
# Move window to workspace and follow
Alt+Shift+1  # Move to workspace 1 and follow
Alt+Shift+2  # Move to workspace 2 and follow
# ... and so on

​
Move Without Following

To move a window to another workspace without switching to it, use the prefix menu: 
Ctrl+B w Shift+1  # Move to workspace 1 (stay on current workspace)
Ctrl+B w Shift+2  # Move to workspace 2 (stay on current workspace)

​
CLI Window Movement

# Move focused window to workspace 3
tuios run-command MoveToWorkspace 3

​
Workspace State

​
Persistence

Each workspace independently maintains:
  • Window positions and sizes - Layouts are preserved per workspace
  • Tiling configuration - Each workspace can have tiling on or off
  • Custom layouts - Manual split configurations persist
  • Focus history - When you return to a workspace, the previously focused window is restored
  • Master ratio settings - Resize adjustments are workspace-specific

​
Session Persistence

When using daemon mode (tuios new / tuios attach), all workspace state persists across detach/reattach: 
# Create a persistent session
tuios new myproject

# Set up workspaces 1-3 with different windows
# ... work for a while ...

# Detach (Ctrl+B d)
# ... later ...

# Reattach - all workspaces and windows are restored
tuios attach myproject

​
Workspace Indicators

The dockbar (status bar) shows workspace information:
  • Current workspace number - Displayed prominently (e.g., WS 1)
  • Window count per workspace - Visual indicators show which workspaces have windows
  • Active workspace highlight - The current workspace is highlighted
Empty workspaces are dimmed in the indicator. This makes it easy to see at a glance which workspaces are in use.

​
Practical Workflows

​
Development Environment Setup

# Workspace 1: Code editor
Alt+1
n  # New window
i  # Enter terminal mode
vim src/main.go

# Workspace 2: Build and test
Alt+2
n
i
go test -v ./...

# Workspace 3: Git operations
Alt+3
n
i
tig  # Or your preferred git UI

# Workspace 4: Server logs
Alt+4
n
i
tail -f /var/log/app.log

​
Quick Context Switch

# Jump between contexts instantly
Alt+1  # Back to code
Alt+4  # Check logs
Alt+2  # Run tests
Alt+1  # Return to code

​
Project Organization

Organize multiple projects across workspaces:
  • Workspace 1-3: Project A (frontend, backend, database)
  • Workspace 4-6: Project B (microservices)
  • Workspace 7: System monitoring
  • Workspace 8: Email/chat clients
  • Workspace 9: Scratch/temporary work

​
Multi-Client Setup

When using SSH or web terminals, each client can be on different workspaces in the same session: 
# Terminal 1: ssh to server
ssh user@server
tuios attach shared
Alt+1  # Work on workspace 1

# Terminal 2: On same server
ssh user@server  
tuios attach shared
Alt+2  # Work on workspace 2

# Both clients share the same session but can view different workspaces

​
Implementation Details

​
Source Code Reference

Workspace functionality is implemented in internal/app/workspace.go with key functions:
  • SwitchToWorkspace(workspace int) - Handles workspace switching with animation cleanup and layout restoration
  • MoveWindowToWorkspace(windowIndex, workspace int) - Moves window without following
  • MoveWindowToWorkspaceAndFollow(windowIndex, workspace int) - Moves and switches
  • GetWorkspaceWindowCount(workspace int) - Counts windows in a workspace

​
Memory Efficiency

Workspaces are lightweight:
  • No duplication of window data
  • Windows store their workspace number
  • State maps are used for per-workspace configuration
  • Only visible windows (current workspace) are rendered

​
Multi-Client Coordination

In daemon mode with multiple clients:
  • Each client can be on a different workspace
  • PTY subscriptions are workspace-aware (only visible windows stream output)
  • Workspace switches are local to each client
  • State synchronization keeps all clients consistent

​
Configuration

Workspace keybindings are configurable in ~/.config/tuios/config.toml: 
# Default workspace switch bindings (Linux)
[keybindings.workspace]
"alt+1" = "SwitchToWorkspace1"
"alt+2" = "SwitchToWorkspace2"
# ... etc

# Default workspace move bindings (Linux)  
"alt+shift+1" = "MoveToWorkspace1AndFollow"
"alt+shift+2" = "MoveToWorkspace2AndFollow"
# ... etc
On macOS, these automatically use opt+ (Option key) instead of alt+.

​
Customizing Workspace Count

Currently, TUIOS supports exactly 9 workspaces. This is a design choice balancing:
  • Single-digit keyboard shortcuts (1-9)
  • Sufficient organization capability
  • Memory and performance efficiency
If you need more separation, consider using multiple sessions (tuios new project1, tuios new project2) instead of more workspaces.

​
Troubleshooting

​
Windows Disappear After Workspace Switch

Cause: You moved a window to another workspace unintentionally. Solution: Check all workspaces by cycling through with Alt+1 through Alt+9. The window is still there.

​
Tiling Broken After Workspace Switch

Cause: Each workspace has independent tiling state. Solution: 
# Re-enable tiling on the current workspace
t  # Toggle tiling on

# Or via prefix
Ctrl+B Space

​
Focus Lost When Switching to Empty Workspace

Expected behavior: When switching to a workspace with no windows, you’re automatically put into Window Management Mode. Press n to create a new window.

​
Workspace State Not Persisting

Cause: Running in local mode instead of daemon mode. Solution: Use persistent sessions: 
# Instead of just "tuios", use:
tuios new mysession  # State persists across detach/reattach
  • Tiling - Each workspace can have independent tiling configuration
  • Sessions - Workspace state persists in daemon mode
  • Keybindings - Customize workspace shortcuts
  • CLI Reference - Remote control commands for workspace management

​
Scripting Examples

​
Create Multi-Workspace Layout

#!/bin/bash
# setup-workspaces.sh - Create a development environment

# Workspace 1: Editor
tuios run-command SwitchWorkspace 1
tuios run-command NewWindow "editor"
tuios send-keys --literal --raw "vim ." && tuios send-keys Enter

# Workspace 2: Terminal
tuios run-command SwitchWorkspace 2  
tuios run-command NewWindow "terminal"

# Workspace 3: Logs
tuios run-command SwitchWorkspace 3
tuios run-command NewWindow "logs"
tuios send-keys --literal --raw "tail -f app.log" && tuios send-keys Enter

# Return to workspace 1
tuios run-command SwitchWorkspace 1

​
Monitor Workspace Usage

#!/bin/bash
# workspace-summary.sh - Show window distribution across workspaces

tuios session-info --json | jq -r '
  .workspace_windows | 
  to_entries | 
  map("Workspace \(.key + 1): \(.value) windows") | 
  .[]'
Output: 
Workspace 1: 3 windows
Workspace 2: 2 windows
Workspace 3: 0 windows
...

Build docs developers (and LLMs) love

Get started for freeTalk to us