atrium — Docs
docs/customization/keybindings.md

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.
  • cmd is the primary modifier: Command on macOS, physical Ctrl on Windows. The separate ctrl role is macOS Control; use alt for Windows combinations that need a second modifier rather than writing cmd+ctrl.
  • The final segment is the key, with letters lowercase. Named keys include enter, tab, escape, space, backspace, delete, up, down, left, right, Home, and End. Punctuation uses the character itself, such as -, =, /, [, or ]; shifted punctuation uses its base key with the shift modifier.
  • 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.