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 uses the theme’s current-match color. 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, and text rendering mode.
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.

In source builds newer than v0.2.0, Appearance → Font → Text rendering offers Natural (default), Legacy, and experimental Linear modes. Linear requires full opacity and an sRGB framebuffer; otherwise it falls back to Natural. See the rendering guide.

Preferences follows the selected theme and rebuilds its font atlas when the framebuffer scale changes.

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; you can scroll (wheel or drag past the edge) to mark text outside the visible area. Copy uses the clipboard; middle-click pastes primary.

The mouse wheel scrolls the pane’s history. If you are scrolled up, Enter (and any other key sent to the shell) jumps back to the live prompt.

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.