Keyboard & UI — traa.sh

01 — Leader

Prefix / leader

Default leader is Ctrl-b (GLFW key 66, mods 1). Press it, then a prefix-bound key. Modifier keys alone do not cancel prefix mode.

Override with config.leader = { key = 66, mods = 1 }. Mods: ctrl=1, shift=2, alt=4, super=8.

Why Ctrl-Shift for app chords: plain Ctrl-C / Ctrl-D / Ctrl-Z must reach the shell. Ctrl-h/j/k/l are the exception — they move pane focus without a prefix.

02 — Defaults

Default keymap

Panes

Chord	Action	Id
Prefix %	Split vertically	`split_v`
Prefix "	Split horizontally	`split_h`
Prefix o	Next pane	`pane_next`
Prefix h / j / k / l	Focus pane	`pane_left` …
Ctrl-h / j / k / l	Focus pane (no prefix)	same
Prefix z	Zoom pane	`zoom`

Windows (tabs)

Chord	Action	Id
Prefix c	New window	`new_window`
Prefix n or Prefix Tab	Next window	`next_window`
Prefix p	Previous window	`prev_window`
Prefix 0–9	Go to window by number	`goto_window`
Prefix d	Detach session	`detach`
Ctrl-Shift-L	Layout picker	`layout_picker`
Ctrl-Shift-O	Session overview	`overview`

Application

Chord	Action	Id
Ctrl-Shift-P	Command palette	`command_palette`
Ctrl-Shift-R	Reload config	`reload_config`
Ctrl-Shift-T	Cycle theme	`theme_cycle`
Ctrl-Shift-F	Search	`search`
Ctrl-Shift-C	Copy selection	`copy`
Ctrl-Shift-V	Paste	`paste`
Ctrl-Shift-,	Settings	`settings`
Ctrl-Shift-/ or Prefix ?	Shortcuts overlay	`shortcuts`
Ctrl-Shift-+	Increase font	`font_increase`
Ctrl--	Decrease font	`font_decrease`
Ctrl-Shift-Q	Quit	`quit`

No default chord: status_cycle and demo — run them from the command palette (or bind them). Reserved: Prefix [ is bound to copy_mode but currently has no runtime handler.

03 — Overview

Two-level session overview

Action overview, default Ctrl-Shift-O. Live cell previews reuse each pane’s existing screen — no extra PTYs or screenshots.

Tabs: one card per open tab with title, pane count, attention badge, and a composite preview of that tab’s pane layout.
Panes: selecting a multi-pane tab drills in. Each card shows title/cwd, a foreground-process indicator, and that pane’s live terminal.
A single-pane tab focuses immediately on Enter or click (no drill-down).

Input	Effect
Arrows or h j k l	Move the selection in the grid
Enter or card click	Drill into panes, or focus the pane and close the overlay
Esc	Panes → tabs, then close
Backspace or u	Back to tabs
×, Delete, or x	Close the selected tab or pane
Backdrop click	Close the overlay

Closing a tab or pane that still has a foreground process opens the same confirmation dialog as quit. Cancel is the default. Closing the last pane of a tab closes the tab. The session always keeps at least one tab.

Overview, shortcuts, and the layout picker are mutually exclusive. The quit dialog stays topmost.

04 — Tabs

Numbered tabs and mouse

New windows take the smallest unused positive number (1, 2, 3…). Closing tab 2 while 1 and 3 exist leaves a gap; the next new tab reuses 2 and inserts in numeric order — not at the end.

Prefix 0–9 jumps to the tab whose number (or name) matches the digit, the same label shown on the tab.

Mouse on the tab bar

Left-click a tab to select it (clears its attention badge).
Click × on a tab to close it.
Click + to create a window.
Middle-click a tab to close it (browser-style). Middle-click in a pane pastes the primary selection.

Inactive-tab attention

An inactive tab gets a pulsing badge when any of its panes produce output, BEL, or OSC 133 command-finished. Selecting the tab clears the badge.

05 — Overlays

Palette, search, shortcuts, layouts

Command palette

Ctrl-Shift-P. Type to filter every action by name/label, then Enter. Also how you run unbound actions such as status_cycle.

Shortcuts overlay

Ctrl-Shift-/ or Prefix ?. Grouped catalog of the current keymap. Click the backdrop or Esc to close.

Search

Ctrl-Shift-F. Status-bar find over scrollback + screen, case-insensitive. All matches highlight; the current one is gold. Enter / F3 / ↓ next; Shift+Enter / Shift+F3 / ↑ previous; Esc closes.

Layout picker

Ctrl-Shift-L. Enter applies, s saves the current session, Del deletes a user layout, Esc closes. Apply replaces all tabs/panes with fresh shells (geometry only).

06 — Settings

Preferences window

Ctrl-Shift-, opens a separate window with three tabs:

Appearance — theme, status bar, default layout, opacity, font family (monospace dropdown from Fontconfig), font size 8–48 px.
Terminal — cursor style, scrollback, enabled plugin list (read-only here; edit config.plugins to change).
Shortcuts — leader and per-action rebinding. Saves into config.keys.

Apply updates the live session; Save writes ~/.config/traash/config.lua.

07 — Pointer

Context menu and selection

Right-click (when no overlay is open) shows: Copy, Paste, Split Right, Split Down, Preferences…

Left-click focuses the pane under the cursor. Double-click selects a word (stops at punctuation and path separators). Drag selects cells. Copy uses the clipboard; middle-click pastes primary.

08 — Font & resize

Zoom, toast, and crisp resize

Live font size is 8–48 px before content-scale. Ctrl-Shift-+ / Ctrl-- (and the matching numpad keys) step one pixel.
A centered toast shows Font size N px.
Layout-aware + / - on the equal/minus keys still work when Shift is involved.
Interactive window resize uses a fast path (no overview thumbnails, deferred PTY resize) so glyphs stay crisp; PTY size flushes after the drag settles.

Numpad Enter is treated as regular Enter in the shell and in every overlay (palette, search, overview, quit, layouts).

09 — Safety

Process-aware quit and close

Ctrl-Shift-Q quits. If any pane still has a foreground process (not just the idle shell), a dialog lists them. Cancel is focused by default. Enter confirms the focused button; y / n also work. The same dialog is reused when overview (or a last-pane close) would kill a running process.

11 — Encrypted attach

Read-only clients

When you attach with the read-only password (or use --read-only), the status bar shows a READ-ONLY badge. The mux server enforces observer mode:

Blocked: keyboard input to the shell, paste, splits, new windows, pane focus commands that change the host layout, layout picker apply.
Allowed: viewing the terminal, scrolling, copy, search, theme/settings (local UI), session overview (read-only mirror).

Attach details and crypto notes: Getting started → Encrypted sessions.

12 — Notifications

Desktop notifications

traash.notify logs and shows a desktop notification. Linux: notify-send (app name traa.sh, 3.5s, transient, replaces the previous traa.sh notification). macOS: Notification Center via osascript.
The on_bell plugin hook fires only while the window is unfocused. Focused BEL stays in-terminal.
The default notify-on-bell plugin further rate-limits to one notification per 15 seconds.