Tape Recording

TUIOS can record your terminal sessions into .tape files that can be replayed, shared, or used for automated testing. Think of it as recording a macro of everything you do in TUIOS.

Quick Start

tuios tape play ~/.local/share/tuios/tapes/my-workflow.tape

Recording Keybindings

All recording commands use the tape prefix menu:

What Gets Recorded

The recorder maps a fixed set of action names to tape commands. Anything outside that set is dropped silently.

Captured

• Window Operations: New, close, minimize, restore all
• Navigation: Next/previous window, select window by number
• Workspaces: Switch workspace
• Layout: Toggle tiling, snap left, snap right, snap fullscreen
• Mode Switches: Window management to terminal mode and back
• Keyboard Input: Text typed in terminals, special keys
• Timing: Automatic delays between actions, emitted as Sleep

Not Captured

• Mouse Events: Clicks, drags, resizes
• Terminal Output: Only input is recorded
• Visual State: Window positions in non-tiling mode
• Copy Mode: Scrollback navigation
• Splits: Split, SmartSplit, RotateSplit, EqualizeSplits, and ToggleZoom have no recorder mapping. A BSP session records as if you never split anything.
• Renames: RenameWindow is not recorded
• Move to workspace: only the switch is recorded, not moving a window across

Managing Recordings

List Recordings

tuios tape list

Shows all recordings with sizes and modification times.

View Contents

tuios tape show my-workflow

Display the tape file. The .tape extension is optional.

Delete Recording

tuios tape delete my-workflow

Show Directory

tuios tape dir

Recording Workflow

Initial State Capture

When recording starts, TUIOS captures:

• Current mode (Window Management or Terminal)
• Active workspace number
• Tiling enabled/disabled

The tape file begins with commands to restore this state during playback.

Timing Capture

Time delays between actions are automatically calculated and inserted as Sleep commands:

NewWindow
Sleep 500ms
TerminalMode
Type "ls -la"
Sleep 200ms
Enter

Typing Buffer

Rapid typing is merged into single Type commands. A flush occurs when:

• 500ms passes with no typing
• Mode switches occur
• Window management actions occur
• Recording stops

Use Cases

Best Practices

Naming Conventions

Use descriptive names:

# Good
dev-setup.tape
project-build.tape
multi-workspace-demo.tape

# Bad
recording-1.tape
test.tape
tmp.tape

Recording for Playback

Keep recordings focused: One task per tape rather than entire sessions.

Start in a clean state: Begin with no windows or a known configuration.

Avoid mistakes: If you make an error, stop and start over. Editing tapes is tedious.

Recording for Documentation

Add comments after recording: Document what each section does:

# Setup development environment
WindowManagementMode
EnableTiling

# Create editor window
NewWindow
Sleep 500ms
TerminalMode
Type "vim main.go"
Enter

Use meaningful window titles: Rename windows during recording for clarity.

Technical Details

Storage Location

Default: ~/.local/share/tuios/tapes/

Follows XDG Base Directory specification. Created automatically on first recording.

File Format

Standard .tape files using the TUIOS tape scripting language. See Tape Scripting for the complete language reference.

Overhead

Recording appends a small struct per action to an in-memory slice and writes the file once, when you stop. There is no per-keystroke disk I/O and no extra work in the render path.

Examples

Example 1: Development Environment

# Recorded: 2024-12-18
# Development environment setup

WindowManagementMode
EnableTiling
Sleep 300ms

# Editor window
NewWindow
Sleep 500ms
TerminalMode
Type "vim main.go"
Enter
Sleep 800ms

# Terminal window
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "go run ."
Enter

Example 2: Multi-Workspace Setup

# Setup project workspaces

WindowManagementMode

# Workspace 1: Coding
SwitchWorkspace 1
EnableTiling
NewWindow
TerminalMode
Type "vim main.go"
Enter

# Workspace 2: Testing
WindowManagementMode
SwitchWorkspace 2
NewWindow
TerminalMode
Type "go test -v ./..."
Enter

# Return to main workspace
WindowManagementMode
SwitchWorkspace 1

Example 3: CI/CD Testing

Record the workflow interactively first. Start TUIOS, press Ctrl+B T r, name it ci-test-suite, create a window with n, enter terminal mode with i, run your test command, then stop with Ctrl+B T s.

The saved tape at ~/.local/share/tuios/tapes/ci-test-suite.tape will look like this:

WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "npm test"
Enter
WaitUntilRegex "Tests passed" 30000

Run it in CI with tape play, which is the subcommand that honours WaitUntilRegex:

#!/bin/bash
set -euo pipefail
tuios tape play ~/.local/share/tuios/tapes/ci-test-suite.tape

tuios new ci --detach
tuios tape exec -s ci ci-test-suite.tape
timeout 60 bash -c 'until tuios capture-pane -s ci | grep -q "Tests passed"; do sleep 1; done'
tuios kill-session ci

Editing Recordings

Tape files are plain text. Edit them to:

• Add comments explaining steps
• Insert additional Sleep commands for pacing
• Add WaitUntilRegex for output synchronization, if you will replay with tape play
• Remove mistakes
• Combine multiple recordings

Before editing:

WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "echo hello"
Enter

After editing:

WindowManagementMode
NewWindow
Sleep 500ms

# Start server and wait for it
TerminalMode
Type "npm start"
Enter
WaitUntilRegex "Server listening" 10000

# Open another window for testing
WindowManagementMode
NewWindow
Sleep 300ms

Troubleshooting

Recording Not Starting

Check tape directory:

ls -la ~/.local/share/tuios/tapes/

If it doesn't exist, TUIOS creates it automatically. Check filesystem permissions if creation fails.

Only one recording at a time: Stop any existing recording with Ctrl+B T s before starting a new one.

Playback Issues

Validate syntax:

tuios tape validate my-recording.tape

Add timing: If playback is too fast, add Sleep commands:

NewWindow
Sleep 500ms  # Add pauses

Clean starting state: Recordings assume a fresh TUIOS session. Start fresh before playback.

Related Documentation