Keyboard and input reference#

This reference includes the Linux Alpha and planned Windows, macOS, and BSD bindings. Use the first-session guide for current release defaults. Explicit entries under [bindings] replace matching default triggers. The compatibility profiles are explicit opt-ins; they never replace the active default implicitly.

Cmd means the macOS Command key. Search and Vi-mode bindings apply only while their mode is active. A terminal application can own a key when the table says the action is mode-sensitive.

Windows and Linux/BSD defaults#

Windows, tabs, and panes#

On Windows, Ctrl+PageUp/PageDown also selects the previous/next window tab and Ctrl+Shift+PageUp/PageDown reorders it. Linux/BSD also supports Ctrl+Shift+[ / Ctrl+Shift+] for previous/next window tab.

Editing, selection, clipboard, and view#

Automexia's Windows Ctrl+V is a host shortcut, so the clipboard reaches the selected pane through the same bracketed-paste and control-filtering path for every child session without synthesizing an extra Enter. To let a terminal application receive the original control character instead, add:

[bindings]
keys = [{ key = "V", with = "control", action = "ReceiveChar" }]

macOS defaults#

Keyboard selection (Shift+Arrow, with Ctrl for horizontal word motion) remains platform-neutral. A pointer click without a drag is never reused as the keyboard anchor. Once a selection exists, an unmodified Arrow key or any non-empty text/paste/IME input exits selection mode before the input is forwarded to the shell. Search and Vi mode retain their own input ownership.

Search mode#

Pane and workspace search are two scopes of one continuous session. Ctrl+F / Cmd+F immediately selects the current pane; Ctrl+Shift+F / Cmd+Shift+F immediately expands to the active local tab in every visible split. Switching keeps the query and query focus, recompiles the match set, and moves the same surface between the pane footer and the safe bottom-centered workspace position. Repeating the shortcut for the active scope only refocuses the query. Hidden pane-local tabs and other window-level tabs remain deliberately excluded.

The PANE and ALL PANES controls are separate, mutually exclusive choices. They are clickable, and Tab / Shift+Tab moves between the query and scope group. With the scope group focused, any arrow key selects the other scope; Space or Enter keeps the selected scope. A pointer selection returns focus to the query. Esc still closes the session. Moving focus to another pane closes a pane-local search instead of silently changing its pane owner.

The result badge reports matches in the visible viewport of the routes in scope, capped at 999+; previous/next navigation still uses the terminal search engine beyond the viewport. Invalid patterns receive an explicit status. The complete painted surface consumes pointer input, and query/control input is limited to 4 KiB of UTF-8 and never reaches the PTY.

Mouse input#

• Drag primary/left mouse to select. Double/triple click expands by semantic unit/line according to terminal selection rules.
• Ctrl+C copies that selection; otherwise it remains interrupt.
• Right-click copies and clears an existing selection. With no selection it pastes through the normal bracketed-paste and control filtering path.
• Middle-click pastes the primary selection on platforms that provide it.
• Left-click never pastes; it owns focus, selection, links, local image preview, and pane activation.
• Mouse-reporting applications keep mouse ownership. Hold Shift for the established host-UI override where supported.

Custom bindings#

Bindings live in config.toml:

[bindings]
keys = [
  { key = "F5", with = "control | shift", action = "ReloadConfig" },
  { key = "O", with = "control | alt", action = "OpenCommandPalette" },
  { key = "PageUp", with = "alt", action = "SelectPrevLocalTab" },
]

Keys are a printable character, named key (home, end, pageup, pagedown, insert, delete, backspace, tab, enter, escape, arrows, or f1…f20), or supported numpad name. Modifiers are control, shift, alt/option, and super/command, joined with |. Modes are appcursor, appkeypad, alt, and vi; prefix a mode with ~ to require its absence. esc sends an explicit escape sequence and takes precedence over action.

Stable action names are case-insensitive:

Paste, Copy, SelectAll,
ExtendSelectionLeft, ExtendSelectionRight, ExtendSelectionUp,
ExtendSelectionDown, ExtendSelectionWordLeft, ExtendSelectionWordRight,
SearchForward, SearchBackward, SearchGlobalForward, SearchGlobalBackward, SearchConfirm, SearchCancel, SearchClear,
SearchFocusNext, SearchFocusPrevious, SearchDeleteWord, SearchHistoryNext,
SearchHistoryPrevious, ClearHistory, ClearScreen,
ResetFontSize, IncreaseFontSize, DecreaseFontSize,
CreateWindow, CloseWindow, ReloadConfig, ToggleQuake,
ScrollToPrevPrompt, ScrollToNextPrompt,
CreateTab, CreateLocalTab, MoveCurrentTabToPrev, MoveCurrentTabToNext,
CloseTab, CloseSplitOrTab, CloseUnfocusedTabs, OpenConfigEditor,
SelectPrevTab, SelectNextTab, SelectPrevLocalTab, SelectNextLocalTab,
SelectLastTab, ScrollPageUp, ScrollPageDown, ScrollHalfPageUp,
ScrollHalfPageDown, ScrollToTop, ScrollToBottom,
SplitRight, SplitDown, CloneSplitRight, CloneSplitDown,
SelectNextSplit, SelectPrevSplit, SelectPaneLeft, SelectPaneRight,
SelectPaneUp, SelectPaneDown, SelectNextSplitOrTab,
SelectPrevSplitOrTab, MoveDividerUp, MoveDividerDown, MoveDividerLeft,
MoveDividerRight, ToggleViMode, ToggleAppearanceTheme, ToggleFullscreen,
OpenCommandPalette, OpenFontBrowser, PreviewSelectedImage, ReceiveChar,
None

Parameterized actions are SelectTab(N), Scroll(N), and Run(PROGRAM ARGS...). Run currently uses a simple whitespace split, not shell parsing; do not use it with untrusted values or arguments that require quoting. Unknown actions are rejected and do not silently remove the matching default.

Ownership and precedence#

Explicit user bindings replace the matching key/modifier/mode trigger. Search, Vi mode, alternate-screen applications, pinned image browsing, terminal mouse reporting, and the line editor each have scoped ownership. Automexia never sends terminal-owned selection motions to the PTY. One global shortcut table is not reused across every mode and operating system because the active surface must keep ownership of its input.

Ghostty compatibility profiles#

automexia remains the implicit profile. Set keyboard.binding-profile to ghostty-1.3 for the pinned Ghostty 1.3.1 profile or to ghostty for the visible moving alias, which currently resolves to ghostty-1.3. User entries and unbind directives are compiled after the selected profile. A failed strict compile or reload leaves the previous complete registry active.

Strict Ghostty bindings use window-level tabs and independent-PTY splits. Bare Ctrl+R and Ctrl+D fall through to the terminal. Platform-global entries are installed through the OS hotkey owner, while focused, all-surface, sequences, tables, chains, performable, and unconsumed policies stay isolated per surface. Unsupported actions remain visibly unavailable; they are never mapped to unrelated behavior.

Complete compatibility tables are not part of the public Alpha guide. Use the default profile unless your installed release documents the alternative you need. Back up bindings before switching and test core actions in a separate session. See Configuration for the broader configuration model.