Rebind keyboard shortcuts and author custom actions
Customize atrium shortcuts in config.keybindings — chord syntax, built-in actions, send-text, protocol commands, unbinding defaults, and live reload.
Every keyboard shortcut in atrium is customizable. The full default map is in Keyboard shortcuts.
Keybindings live under config.keybindings in ~/.atrium/config.json. The in-app editor is at Settings → Keyboard.
Chord format
A chord is a string like "cmd+shift+d" or "alt+ctrl+k". Rules:
- Write modifiers in canonical order:
alt,cmd,ctrl,shift, followed by the key. The recorder saves this form for you. cmdis the primary modifier: Command on macOS, physical Ctrl on Windows. The separatectrlrole is macOS Control; usealtfor Windows combinations that need a second modifier rather than writingcmd+ctrl.- The final segment is the key, with letters lowercase. Named keys include
enter,tab,escape,space,backspace,delete,up,down,left,right,Home, andEnd. Punctuation uses the character itself, such as-,=,/,[, or]; shifted punctuation uses its base key with theshiftmodifier. - Chords are single-key only today. Two-step sequences (VS Code-style
Cmd+K Cmd+S) are not yet supported.
Action types
Every binding maps to an object with an action field.
Built-in actions
Triggers a built-in atrium operation:
{
"cmd+d": { "action": "split-horizontal" },
"cmd+shift+w": { "action": "close-tab" }
}
The full action list is visible in Settings → Keyboard. Internal action names retain some older terminology: close-tab closes a room, for example.
send-text
Sends raw text to the focused pane's PTY stdin. Useful for binding escape sequences or canned inputs:
{
"shift+enter": { "action": "send-text", "text": "\n" },
"alt+enter": { "action": "send-text", "text": "\r\n" }
}
Recognized escapes: \n (newline), \r (carriage return), \t (tab), \\ (literal backslash). Use \u001b for ESC when writing raw escape sequences.
uri-command
Dispatches an atrium:// protocol URI. This is the most flexible form — the URI resolver routes to pane, project, command, and hook operations. See atrium:// protocol.
{
"cmd+shift+m": {
"action": "uri-command",
"command": "atrium://commands/launcher.open"
}
}
Unbinding a default
Set a binding to null to remove a default:
{
"cmd+b": null
}
This removes atrium's default for that chord without replacing it.
Multiple shortcuts per action
The map is chord → action, so two chords can trigger the same command. Defaults already do this for Zoom In (Cmd+= and Cmd+Shift+=) and Omni-search (Cmd+K and Cmd+Shift+T). In Settings → Keyboard, click Add on a row to record another chord for that action. Each extra chord also works as a config.keybindings entry pointing at the same action.
Hand-editing vs the UI
The Settings UI covers the common case. You can hand-edit config.json for bulk changes or templated setups; atrium watches the file and reloads on change. Menu accelerators (the macOS native menu shortcuts) stay in sync with your keybindings automatically — you do not need to edit them separately.
Applying changes without a restart
Keybinding changes apply immediately in the current app session. The recorder accepts chords already assigned to another action, so you can reassign them from Settings.
Defaults you cannot overwrite
A small set of OS-level shortcuts (macOS's Command-Q, Command-Tab, Mission Control, and so on) are intercepted by the OS before atrium sees them. atrium does not override them.