Sessions & Daemon Mode

TUIOS supports persistent sessions through a daemon process, similar to tmux or screen. Sessions continue running in the background even when you disconnect, allowing you to reattach later with all windows and terminal content preserved.

Quick Start

# Create a new session
tuios new mysession

# Work in TUIOS, then detach
# Press Ctrl+B d

# Later, list sessions
tuios ls

# Reattach to continue
tuios attach mysession

Creating Sessions

Use tuios new to create a new persistent session:

# Auto-generated session name
tuios new

# Named session
tuios new work

# With options
tuios new dev --theme dracula --show-keys

Session Naming

• Session names can contain letters, numbers, hyphens, and underscores
• If no name is provided, a unique name is auto-generated
• Session names must be unique

Listing Sessions

View all sessions with tuios ls:

tuios ls

Output:

╭───────────────┬─────────┬──────────┬───────────────┬─────────────────╮
│ NAME          │ WINDOWS │ STATUS   │ CREATED       │ LAST ACTIVE     │
├───────────────┼─────────┼──────────┼───────────────┼─────────────────┤
│ work          │ 3       │ detached │ 2 hours ago   │ 5 mins ago      │
│ dev           │ 2       │ attached │ 1 day ago     │ just now        │
╰───────────────┴─────────┴──────────┴───────────────┴─────────────────╯

Attaching to Sessions

Reattach to a session with tuios attach:

# Attach to specific session
tuios attach work

# Attach to most recent session (if only one)
tuios attach

# Attach and create if session doesn't exist
tuios attach work -c

Detaching from Sessions

Detach from a session without closing it:

After detaching, the session continues running in the background.

Managing Sessions

Kill a Session

Remove a specific session:

tuios kill-session work

Stop the Daemon

Stop the TUIOS daemon and all sessions:

tuios kill-server

How It Works

1. Daemon Process: When you create your first session, TUIOS starts a background daemon that manages all sessions
2. Socket Communication: TUI clients communicate with the daemon over a Unix socket
3. PTY Persistence: Terminal PTYs are owned by the daemon, not the client, so they survive disconnection
4. State Sync: Window positions, workspace layout, and terminal content sync continuously

Multi-Client Support

Multiple clients can connect to the same session simultaneously. All clients see synchronized state in real-time.

How It Works

When you attach multiple terminals to the same session:

• All clients share the same windows and workspaces
• Actions from one client are reflected on all others
• The effective terminal size is the minimum of all connected clients

Notifications

TUIOS displays notifications for multi-client events:

Example: Pair Programming

# Terminal 1: Create session
tuios new pairing

# Terminal 2: Attach to same session
tuios attach pairing

# Both terminals now show the same TUIOS instance
# Actions in either terminal are reflected in both

Session Lifecycle

Daemon Location

The daemon socket is located at:

• Linux: $XDG_RUNTIME_DIR/tuios/tuios.sock or /tmp/tuios-$UID/tuios.sock
• macOS: /tmp/tuios-$UID/tuios.sock
• Windows: %LOCALAPPDATA%\tuios\tuios.sock

Remote Control

One of the most powerful features of daemon sessions is the ability to control them from external scripts and tools. TUIOS provides CLI commands to send keystrokes, execute commands, and query state.

Send Keystrokes

Send input to a running session:

# Enter terminal mode
tuios send-keys i

# Send key combo
tuios send-keys "ctrl+b q"

# Send to specific session
tuios send-keys -s mysession Escape

# Send literal text to terminal (use --raw to prevent space splitting)
tuios send-keys --literal --raw "echo hello"

Run Commands

Execute TUIOS commands remotely:

# Create a new window
tuios run-command NewWindow "my-terminal"

# Get JSON output with window ID
tuios run-command --json NewWindow "dev"

# Switch workspace
tuios run-command SwitchWorkspace 2

# Toggle tiling
tuios run-command ToggleTiling

# Target specific session
tuios run-command -s mysession NewWindow "dev"

Query State

Inspect session state for scripting:

# List all windows
tuios list-windows --json

# Get focused window info
tuios get-window --json

# Get session state
tuios session-info --json

Example: Development Layout Script

#!/bin/bash
# Create a development environment

# Create windows and capture IDs
EDITOR=$(tuios run-command --json NewWindow "editor" | jq -r '.data.window_id')
TERM=$(tuios run-command --json NewWindow "terminal" | jq -r '.data.window_id')
LOGS=$(tuios run-command --json NewWindow "logs" | jq -r '.data.window_id')

# Enable tiling
tuios run-command ToggleTiling

# Start applications
tuios send-keys --literal --raw "nvim ." && tuios send-keys Enter
tuios run-command FocusWindow "$TERM"
tuios run-command FocusWindow "$LOGS"
tuios send-keys --literal --raw "tail -f app.log" && tuios send-keys Enter

Example: Window Selector with fzf

#!/bin/bash
WINDOW=$(tuios list-windows --json | \
    jq -r '.windows[] | "\(.display_name)\t\(.id)"' | \
    fzf --with-nth=1 | cut -f2)

[ -n "$WINDOW" ] && tuios run-command FocusWindow "$WINDOW"

Best Practices

Naming Conventions

Use descriptive session names:

tuios new project-frontend
tuios new project-backend
tuios new personal

Workspace Organization

Combine sessions with workspaces:

• Use sessions for different projects or contexts
• Use workspaces within a session for related tasks

Clean Up

Regularly remove unused sessions:

tuios ls              # Review sessions
tuios kill-session old-project

Troubleshooting

"Daemon not running"

If you see this error, the daemon may have crashed. Start fresh:

tuios kill-server     # Clean up any stale socket
tuios new mysession   # Start new daemon

"Session not found"

The session may have been killed or the name is incorrect:

tuios ls              # Check available sessions
tuios attach <name>   # Use exact name

Stale Sessions

If a session becomes unresponsive:

tuios kill-session stuck-session
tuios new fresh-session

Related