Keybindings Reference

Complete keyboard shortcut reference for TUIOS. All keybindings are customizable through the configuration file.

Quick Tip

Press Ctrl+B then ? from anywhere in TUIOS to see the help overlay!

Modes

Mode switching is configured in [keybindings.mode_control]. TUIOS has two main modes:

Window Management Mode - Navigate and manage windows (default on startup)
Terminal Mode - Input goes directly to the focused terminal

Mode Switching

i or Enter - Enter Terminal Mode
Alt+Esc or Opt+Esc - Exit Terminal Mode (direct shortcut)
Ctrl+B then Esc - Return to Window Management Mode (from Terminal Mode)
? (Window Mode) or Ctrl+B then ? (universal) - Toggle help overlay
q (Window Mode) or Ctrl+B then q (universal) - Quit TUIOS

Esc and d are not the same thing

Ctrl+B Esc leaves terminal mode and returns you to window mode. It never detaches.

Ctrl+B d detaches from a daemon session, leaving it running in the background. These were one action in older versions and are now separate: prefix_exit_mode and prefix_detach.

Terminal Mode Shortcuts

These shortcuts work directly in Terminal Mode without requiring the prefix key. Configured in [keybindings.terminal_mode].

Platform	Next Window	Previous Window	Exit Terminal Mode
macOS	`Opt`+`Tab`	`Opt`+`Shift`+`Tab`	`Opt`+`Esc`
Linux/Windows	`Alt`+`N`	`Alt`+`P`	`Alt`+`Esc`

Why different keybindings?

On Linux and Windows, Alt+Tab is captured by the OS window switcher, so TUIOS uses Alt+N/Alt+P instead. On macOS, Opt+Tab produces a unicode character that TUIOS can intercept.

Window Management

Window mode, from [keybindings.window_management] (and [keybindings.restore_minimized] for the last row).

z - Toggle zoom (fullscreen focused window). Shared borders hidden when zoomed, dockbar shows Z indicator.
n - Create new window
w or x - Close focused window
r - Rename focused window
m - Minimize focused window
Shift+M - Restore all minimized windows
Tab - Focus next window
Shift+Tab - Focus previous window
1-9 - Select window by number
Shift+1-9 or !@#$%^&*( - Restore minimized window by number

Workspaces

TUIOS supports 9 workspaces for organizing windows. Configured in [keybindings.workspaces].

Alt+1 through Alt+9 - Switch to workspace 1-9
Alt+Shift+1 through Alt+Shift+9 - Move window to workspace and follow

macOS Users

Use Option+1 through Option+9 (automatically configured by default)

Window Layout

Manual Snapping (Non-Tiling Mode)

Keyboard Snapping

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

Mouse Edge Snapping

In floating mode (non-tiling), drag a window to the screen edges to snap it:

Edge	Action
Top center	Fullscreen
Left edge	Snap to left half
Right edge	Snap to right half
Top-left corner	Snap to top-left quarter
Top-right corner	Snap to top-right quarter
Bottom-left corner	Snap to bottom-left quarter
Bottom-right corner	Snap to bottom-right quarter

Edge Detection

Simply drag a window by its title bar and release when the cursor reaches the screen edge (within 5 pixels of the edge).

Tiling Mode

TUIOS uses Binary Space Partitioning (BSP) for automatic tiling. Windows are arranged in an alternating vertical/horizontal split pattern (spiral layout).

t - Toggle automatic tiling mode
Shift+H or Ctrl+Left - Swap with window to the left
Shift+L or Ctrl+Right - Swap with window to the right
Shift+K or Ctrl+Up - Swap with window above
Shift+J or Ctrl+Down - Swap with window below
< or Shift+, - Decrease master window width (from right edge)
> or Shift+. - Increase master window width (from right edge)
{ or Shift+[ - Decrease focused window height (from bottom edge)
} or Shift+] - Increase focused window height (from bottom edge)
. - Increase master window width from the left edge
[ - Decrease focused window height from the top edge
] - Increase focused window height from the top edge

One default binding you cannot reach

resize_master_shrink_left is bound to a bare , by default, and you will never trigger it. In window mode, , is intercepted for the settings page before any keybinding lookup runs.

Rebinding , in [keybindings.layout] does not help either, because the intercept is not registry-driven. Bind resize_master_shrink_left to a different key if you want it.

BSP Split Controls

In window mode, from [keybindings.layout]:

- - split_horizontal
| or \ - split_vertical
R - rotate_split
= - equalize_splits
Alt+h Alt+j Alt+k Alt+l - preselect_left / preselect_down / preselect_up / preselect_right, choosing where the next window lands (Opt on macOS)

The same four split operations are also on the prefix key, as separate actions in [keybindings.prefix_mode]:

Ctrl+B then - - prefix_split_horizontal
Ctrl+B then | or \ - prefix_split_vertical
Ctrl+B then R - prefix_rotate_split
Ctrl+B then = - prefix_equalize_splits

Rebinding one does not rebind the other. They are two independent sets.

Split Indicator

The dock shows the next split direction (V for vertical, H for horizontal) when tiling mode is active.

Copy Mode

Enter copy mode with Ctrl+B then [ to navigate scrollback and select text using vim-style commands.

Vim Users

Copy mode supports 50+ vim motions including word movements, paragraph jumps, and search!

Ctrl+B then [ - Enter copy mode
h j k l - Move cursor left/down/up/right
w b e - Word forward / word backward / word end
0 ^ $ - Start of line / first non-blank / end of line
gg - Jump to top of scrollback
G - Jump to bottom (live output)
{number}G - Jump to line number (e.g., 10G)
{ } - Jump to previous/next paragraph
Ctrl+U Ctrl+D - Half page up/down
Ctrl+B Ctrl+F - Full page up/down
i - Return to terminal mode
q or Esc - Exit copy mode

Count Prefix

Prefix any motion with a number to repeat it:

10j - Move down 10 lines
5w - Move forward 5 words
3{ - Jump up 3 paragraphs

Character Search

f{char} - Find next occurrence of char on line
F{char} - Find previous occurrence of char on line
t{char} - Move cursor before next char
T{char} - Move cursor after previous char
; - Repeat last character search
, - Repeat last search (opposite direction)

Search

/ - Search forward
? - Search backward
n - Next match
N - Previous match
Ctrl+L - Clear search highlights

Visual Selection

v - Enter visual character mode
V - Enter visual line mode
y or c - Yank (copy) selection to clipboard
Esc or q - Exit visual mode

Command Palette

Ctrl+P - Open Command Palette (works from any mode)
Ctrl+B then P - Open Command Palette (prefix alternative)

The command palette provides fuzzy-searchable access to all TUIOS commands, keybindings, and actions.

Prefix Commands

Press Ctrl+B, release, then press the command key (tmux-style).

Leader Key

The leader key (Ctrl+B by default) is configurable. See Configuration Guide for details.

Main Prefix (`Ctrl`+`B`)

Every row below is an action in [keybindings.prefix_mode] and can be rebound.

Key	Action name	Does
`c`	`prefix_new_window`	Create new window
`x`	`prefix_close_window`	Close current window
`r`	`prefix_rename_window`	Rename window
`,`	`prefix_settings`	Open the settings page
`n` or `Tab`	`prefix_next_window`	Next window
`p` or `Shift`+`Tab`	`prefix_prev_window`	Previous window
`0`-`9`	`prefix_select_0` to `prefix_select_9`	Jump to window
`Space`	`prefix_toggle_tiling`	Toggle tiling mode
`z`	`prefix_fullscreen`	Toggle zoom on current pane
`-`	`prefix_split_horizontal`	Split horizontally (top/bottom)
`\|` or `\`	`prefix_split_vertical`	Split vertically (left/right)
`R`	`prefix_rotate_split`	Rotate split direction
`=`	`prefix_equalize_splits`	Equalize all split ratios
`[`	`prefix_selection`	Enter copy mode
`s`	`prefix_scrollback`	Open the scrollback browser
`S`	`prefix_session_switcher`	Open the session switcher
`P`	`prefix_command_palette`	Open the command palette
`L`	`prefix_layout`	Enter layout prefix menu
`w`	`prefix_workspace`	Enter workspace prefix menu
`m`	`prefix_minimize`	Enter minimize prefix menu
`t`	`prefix_window`	Enter window prefix menu
`D`	`prefix_debug`	Enter debug prefix menu
`T`	`prefix_tape`	Enter tape prefix menu
`d`	`prefix_detach`	Detach; a daemon session keeps running
`Esc`	`prefix_exit_mode`	Leave terminal mode, never detaches
`q`	`prefix_quit`	Quit; in daemon mode this kills the session
`?`	`prefix_help`	Toggle help

Ctrl+B then Ctrl+B sends a literal Ctrl+B to the terminal.

Copy mode and the scrollback browser are different

Ctrl+B [ enters copy mode, with vim motions and text selection. Ctrl+B s opens the scrollback browser, which is for reading back through history. They are separate actions with separate bindings.

Window Prefix (`Ctrl`+`B` then `t`)

Configured in [keybindings.window_prefix].

n - window_prefix_new, create new window
x - window_prefix_close, close current window
r - window_prefix_rename, rename window
Tab - window_prefix_next, next window
Shift+Tab - window_prefix_prev, previous window
t - window_prefix_tiling, toggle tiling mode
Esc - window_prefix_cancel, cancel

Minimize Prefix (`Ctrl`+`B` then `m`)

Configured in [keybindings.minimize_prefix].

m - minimize_prefix_focused, minimize the focused window
1-9 - minimize_prefix_restore_1 to minimize_prefix_restore_9, restore minimized window by position
M - minimize_prefix_restore_all, restore all minimized windows
Esc - minimize_prefix_cancel, cancel

Tape Prefix (`Ctrl`+`B` then `T`)

Record and replay .tape automation scripts. Configured in [keybindings.tape_prefix].

m - tape_prefix_manager, open the tape manager
r - tape_prefix_record, start recording
s - tape_prefix_stop, stop recording
Esc - tape_prefix_cancel, cancel

Workspace Prefix (`Ctrl`+`B` then `w`)

Configured in [keybindings.workspace_prefix].

1-9 - workspace_prefix_switch_1 to workspace_prefix_switch_9, switch to workspace
! @ # $ % ^ & * ( - workspace_prefix_move_1 to workspace_prefix_move_9, move window to workspace and follow
Esc - workspace_prefix_cancel, cancel

Debug Prefix (`Ctrl`+`B` then `D`)

Debug and development tools. Configured in [keybindings.debug_prefix].

l - debug_prefix_logs, toggle log viewer
c - debug_prefix_cache, toggle cache statistics
k - debug_prefix_showkeys, toggle showkeys overlay
a - debug_prefix_animations, toggle animations
Esc - debug_prefix_cancel, cancel

Layout Prefix (`Ctrl`+`B` then `L`)

Save and load window layout templates:

Ctrl+B then L then l - Load layout template
Ctrl+B then L then s - Save layout template
Ctrl+B then L then Esc - Cancel

Layout loading is non-destructive: existing windows are repositioned to match the template rather than being killed. Extra windows are minimized.

The only prefix menu you cannot rebind

Entering this menu is the configurable prefix_layout action, but l and s inside it are literal. The layout sub-prefix has no config section of its own.

Mouse Controls

Left Click - Focus window
Left Drag - Move window (non-tiling) or swap windows (tiling)
Right Drag - Resize window (non-tiling only)
Title Bar Buttons - Minimize, maximize, or close window
Click Dock Item - Restore minimized window
Copy Mode Click - Move cursor to position
Copy Mode Drag - Select text (enters visual mode). Dragging above/below the pane auto-scrolls via a timer.
Mouse Wheel Up - Enter copy mode and scroll up (when the application is not tracking the mouse and is not on the alternate screen)
Right Border Click/Drag - Interactive scrollbar for navigating scrollback history

Customization

Every binding on this page lives in one of 14 sections under [keybindings] in config.toml, and every one is rebindable. The section is named next to each group above. See the Configuration Guide for the full list and the key syntax.

# Edit your keybindings
tuios config edit

# View current configuration
tuios keybinds list

# View your customizations
tuios keybinds list-custom

Prefix bindings work now

Six sections used to be parsed and then ignored, so rebinding anything under the leader key silently did nothing: prefix_mode, window_prefix, minimize_prefix, workspace_prefix, debug_prefix, and tape_prefix. They all resolve properly now, as does terminal_mode. If you gave up on customizing your prefix menus, try again.

list-custom is not a full audit

tuios keybinds list-custom compares 9 of the 14 sections. It ignores navigation, restore_minimized, debug_prefix, tape_prefix, and terminal_mode, and it never reports a customized leader_key. A config that changes only those prints "No custom keybindings configured".

Most keybinding changes need a restart

TUIOS hot-reloads part of [appearance], but keybindings are not in that subset. Restart the client after editing them.

Platform-Specific Notes

macOS

Default workspace switching uses Option key:

Option+1 through Option+9 - Switch workspace
Option+Shift+1 through Option+Shift+9 - Move window to workspace

Terminal mode shortcuts:

Opt+Tab / Opt+Shift+Tab - Cycle windows
Opt+Esc - Exit terminal mode

You can still type Option key unicode characters (¡™£¢∞§¶•ª) in Terminal Mode.

Linux/Windows

Uses standard Alt key for workspace switching:

Alt+1 through Alt+9
Alt+Shift+1 through Alt+Shift+9