Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Keyboard Bindings

Mosaico registers global system hotkeys that work regardless of which application has focus. Keybindings are configured in ~/.config/mosaico/keybindings.toml.

Default Keybindings

The defaults use vim-style spatial navigation (H=left, J=down, K=up, L=right). For a printable one-page reference, see the Cheatsheet.

ShortcutAction
Alt + HFocus left
Alt + JFocus down
Alt + KFocus up
Alt + LFocus right
Alt + Shift + HMove left
Alt + Shift + JMove down
Alt + Shift + KMove up
Alt + Shift + LMove right
Alt + Shift + RRetile
Alt + TToggle monocle
Alt + NCycle layout
Alt + MMinimize focused window
Alt + QClose focused window
Alt + 1 .. Alt + 8Switch to workspace 1-8
Alt + Shift + 1 .. Alt + Shift + 8Send window to workspace 1-8
Alt + Shift + PToggle pause / resume

Configuration Format

Each binding is a [[keybinding]] entry with three fields:

[[keybinding]]
action = "focus-left"
key = "H"
modifiers = ["alt"]

[[keybinding]]
action = "move-left"
key = "H"
modifiers = ["alt", "shift"]

Actions

ActionDescription
focus-leftFocus the window to the left
focus-rightFocus the window to the right
focus-upFocus the window above
focus-downFocus the window below
move-leftMove window left (swap or cross-monitor)
move-rightMove window right
move-upMove window up (swap on same monitor)
move-downMove window down
retileRe-apply the tiling layout, with the splits you moved back at the configured ratio, or an equal share in a stack, and the windows you floated tiled again
toggle-monocleToggle monocle (full-screen) mode
toggle-floatFloat the focused window above the tiles, or tile it again
cycle-floatFocus the next floating window of the workspace on screen
grow-width / shrink-widthWiden or narrow the focused window by one step: a floating one around its center, a tiled one by moving the split beside it
grow-height / shrink-heightHeighten or shorten the focused window by one step: a floating one around its center, a tiled one by moving the split beside it
cycle-layoutCycle to the next tiling layout (BSP -> VStack -> 3Col)
close-focusedClose the focused window
minimize-focusedMinimize the focused window
goto-workspace-NSwitch to workspace N (1-8)
goto-workspace-nextSwitch to the workspace after the one on screen
goto-workspace-prevSwitch to the workspace before the one on screen
send-to-workspace-NSend focused window to workspace N (1-8)
toggle-pauseToggle hotkey pause on/off

goto-workspace-next and goto-workspace-prev have no default shortcut. Past the last workspace they stop, or go round to the first with [workspaces] wrap = true in config.toml. For example:

[[keybinding]]
action = "goto-workspace-next"
key = "Right"
modifiers = ["alt", "ctrl"]

Modifiers

ModifierKey
altAlt key
shiftShift key
ctrlControl key
winWindows key

Supported Keys

Key TypeExamples
LettersA – Z (case-insensitive)
Digits0 – 9
Function keysF1 – F24
Named keysEnter, Tab, Escape, Space
Arrow keysLeft, Right, Up, Down
PunctuationMinus, Plus, Comma, Period

Unknown key names are skipped with a log message.

Pause / Unpause

If another application uses the same global shortcuts as mosaico, you can temporarily release mosaico’s hotkeys so that application can receive them:

[[keybinding]]
action = "toggle-pause"
key = "P"
modifiers = ["alt", "shift"]

Press Alt+Shift+P to pause — the status bar shows a red PAUSED indicator. Press it again, or click the indicator, to resume. You can also use the CLI:

mosaico pause
mosaico unpause

The toggle-pause hotkey stays registered while paused so you can always resume from the keyboard without opening a terminal.

Launching Applications

A [[launch]] table binds a shortcut to a program instead of an action:

# Start a new terminal every time.
[[launch]]
command = "wt.exe"
key = "Enter"
modifiers = ["alt"]

# Bring an open Edge window into view, or start Edge when none is open.
[[launch]]
command = "msedge.exe"
args = ["--new-window"]
key = "B"
modifiers = ["alt", "shift"]
focus = true

# Windows Terminal's windows belong to WindowsTerminal.exe, not wt.exe, so say
# which windows count as already open.
[[launch]]
command = "wt.exe"
key = "T"
modifiers = ["alt", "shift"]
focus = true
match_path = "WindowsTerminal.exe"
FieldRequiredMeaning
commandyesThe program to start, as you would type it in the Run box (Win+R): a name Windows finds on its own (on PATH or registered, like msedge.exe), a full path, or a URI such as ms-settings:. Environment variables like %USERPROFILE% are expanded.
argsnoArguments, one string each. Paths with spaces need no extra quotes.
key, modifiersyesAs in [[keybinding]].
focusnotrue brings an open window of the program into view instead of starting it. Default false.
match_path, match_class, match_titlenoWhich windows count as the program’s, with the same meaning as in window rules. Only read with focus = true.

A new instance, or the open window

By default, every press starts the program again, and mosaico never looks for an open window. A program that allows only one instance decides itself what a second start does; many simply bring their window forward.

With focus = true, a press brings an open window of the program into view and focuses it: its monitor switches to the window’s workspace when that is out of view, as when you pick it from the taskbar, and monocle is left when another window fills the screen in front of it. Pressing again cycles through the program’s windows. When none is open, the program starts. Only windows mosaico manages count, so splash screens and tool windows are skipped.

Without any match_* field, a window counts when the name of its executable, without extension, is the name of command, ignoring case: msedge.exe matches the windows of msedge.exe. When the program you start is not the one that owns the windows, as with wt.exe and WindowsTerminal.exe, say which windows to look for with match_path.

The program starts in your home folder. A command Windows cannot find is not turned into a web search: mosaico shows a notification beside its tray icon naming the command and why it did not start, and logs the error. Without the tray icon, the error is only logged. There are no default launch bindings; the template has commented examples, and auto-merge leaves [[launch]] tables alone. A launch binding sharing a shortcut with an action or another launch binding is a conflict, reported by mosaico doctor and the settings app.

You can also add, edit and remove launch bindings on the Applications tab of the Keybindings page in the settings app.

Auto-merge

On each daemon start, any default keybinding actions not present in your keybindings.toml are automatically appended to the file. This ensures you pick up new shortcuts added in future versions without overwriting any of your customizations. Actions you’ve already bound (even to different keys) are never touched.

Reloading

Keybinding changes are hot-reloaded. When keybindings.toml changes, the daemon gives back every hotkey and registers the ones the file now holds, launch bindings included, so a shortcut saved in the settings app works at once. While the hotkeys are paused they stay paused. A file that does not load is reported beside the tray icon and the keys in use stay until it is fixed. New default actions are appended to the file only when the daemon starts.