Keybindings¶

Roost uses platform-native modifiers: Cmd on macOS. On Linux, Alt is the app modifier (the role Cmd plays on macOS), leaving Ctrl to the shell — the only Ctrl defaults are Ctrl-1…Ctrl-9 (switch tab) and Ctrl-Shift-C / Ctrl-Shift-V (copy/paste). The same actions are available on both platforms — only the modifier differs.

Every binding is overridable in config.conf (see Custom keybindings) — e.g. keybind = ctrl+t = new_tab restores the pre-Alt Alt-T chord.

macOS¶

Tab management (active project)¶

Project management¶

Commands¶

Clipboard¶

Bare Ctrl-C is left as SIGINT — it's not overloaded for copy.

Font sizing¶

Font size adjustments are per-tab and held in memory only. They do not persist across restarts, and new tabs always start at font_size from config.conf. The size is clamped to 6 .. 72 points; out-of-range steps saturate.

Linux¶

Tab management (active project)¶

Project management¶

Commands¶

Clipboard¶

Bare Ctrl-C is left as SIGINT — it's not overloaded for copy. Copying (or simply finishing a drag-selection) also writes to the X11/Wayland PRIMARY clipboard, so middle-click paste in other apps — and into Roost — works.

Font sizing¶

Font size adjustments are per-tab and held in memory only. They do not persist across restarts, and new tabs always start at font_size from config.conf. The size is clamped to 6 .. 72 points; out-of-range steps saturate.

Terminal keys¶

Anything not bound as an app shortcut flows to the focused terminal through libghostty-vt's key encoder, which produces the right escape sequence for the foreground app's current modes (legacy xterm, application-cursor, Kitty keyboard protocol, etc.):

Ctrl-1 … Ctrl-9 are reserved for tab switching and do not reach the shell. On macOS, all Cmd-* and Super-* combinations are reserved for app shortcuts and never reach the shell.

How the shortcut controller is wired¶

App shortcuts are resolved before the keystroke is offered to the terminal, on both UIs. That's why Cmd-T (or Alt-T on Linux) works while the terminal is focused: the shortcut table is consulted first, the action dispatches, and the keystroke never reaches the shell. Anything not in the table falls through to the terminal as usual.

On macOS this is the AppKit main menu plus the window's own key handling. On Linux the iced UI handles every key press in one place: the terminal widget deliberately never captures keyboard events, so they arrive at the app-level handler (App::keyboard in crates/roost-iced/src/app.rs), which walks a fixed order — an open modal or inline rename first, then the command palette, then the keybinding table, and only then the terminal. There is no toolkit focus-traversal to fight: Tab and Shift-Tab are ordinary keys that fall straight through to the encoder.

Mouse¶

Selection clears automatically on any PTY output, on resize, and on a new click. (Most terminals clear-on-any-output rather than tracking which rows changed; matches user expectation and avoids the bookkeeping.)

Opening links¶

Hold the link modifier and hover a URL to highlight it (underline + hand cursor); click while holding it to open the URL in your default browser. This works for both OSC 8 hyperlinks (what tools like Claude Code emit) and plain https://… text matched on screen.

The modifier is platform-native by default — Cmd on macOS, Alt on Linux — and configurable via link-modifier in config.conf. Linux users who prefer the conventional Ctrl+click set link-modifier = ctrl. (Some Linux WMs grab Alt+drag to move windows, so Ctrl can be the more reliable choice.) The link-modifier setting is honored by the iced UI; the Swift Mac app is fixed to Cmd. See config.md for details and the broader "prefer Ctrl on Linux" recipe.

Pressing any input-producing key when the viewport is scrolled back snaps the viewport to the bottom before delivering the keystroke — same behavior as every other terminal multiplexer.

Sidebar mouse¶

The sidebar still supports mouse-driven rename: double-click a project row to rename it inline, or right-click for a Rename / Close menu.

If you close the last tab in a project, Roost closes that project too. The "Are you sure?" confirmation dialog only appears for explicit close-project actions (the sidebar X button or the right-click menu); Cmd-W / Alt-W on the final tab closes the project silently.

Tab titles set via Cmd-R / Alt-R are persisted and locked: subsequent OSC 1/2 escapes from the shell (\e]2;new-title\a, common in shell prompts) are silently ignored on a renamed tab. The same lock applies to titles set via roostctl set-title --tab <id> --title "...". v1 has no in-app way to clear the lock; renaming again with Cmd-R / Alt-R updates the displayed label but the lock stays on. To revert to shell-driven titles, delete and recreate the tab.

Custom keybindings¶

Roost reads ~/.config/roost/config.conf (more precisely $XDG_CONFIG_HOME/roost/config.conf) on both platforms. The keybinding syntax mirrors Ghostty:

keybind = trigger = action

Each keybind line either binds a trigger to an action, or unbinds one. Multiple keybind lines accumulate; later lines override earlier ones for the same trigger (last-wins per trigger).

Modifiers¶

Combine with +. Aliases are accepted on both sides:

The key segment is the last token that isn't a modifier; it's matched case-insensitively by name (t, 1, tab, return, bracketleft, plus, …) against the same name the UI derives from the pressed key. On a non-Latin keyboard layout the physical key's Latin equivalent is used, so super+t still fires where a QWERTY T sits.

Examples¶

# Add Cmd-J as a second trigger for new_tab. Cmd-T (the default) still works.
keybind = super+j = new_tab

# Disable the default rename-project shortcut.
keybind = super+shift+r = unbind

# Reassign Cmd-T to close the active tab. Cmd-W still also closes (default).
keybind = super+t = close_tab

Use only leading-line # comments. A # after a keybind value is treated as part of the action string, not as an inline comment.

Available actions¶

Defaults with multiple triggers (cycle_tab_*, paste, copy) keep both triggers; an unbind line removes only the listed one.

Triggers using Ghostty prefixes (global:, all:, unconsumed:, performable:) and unknown action names are logged and skipped — they're out of scope for v1.

The config file is read once at startup; restart Roost to pick up edits.