Skip to content

Keyboard shortcuts

Configure the live CompozyOS keymap, inspect effective bindings, and apply the Terminal preset.

5 min read10 pages in Configuration

On this page7

CompozyOS keeps shortcut defaults in the daemon. The web app, Settings, and the keyboard reference all read the same effective keymap: daemon defaults plus your validated overrides.

Inspect the keymap

Use the Settings API when you need the typed contract:

curl http://localhost:2123/api/settings/window-manager

The response separates stored and effective state:

  • config.shortcuts: only stored overrides.
  • effective_shortcuts: the complete map used by the shell now.
  • aliases: workspace aliases keyed by command ID.
  • commands: registry metadata used to group every bindable command by source.
  • extension_defaults: extension-provided defaults, including dormant conflicts.

The CLI exposes the same discovery data under value:

compozy config get window_manager -o json

Configure a binding

Each action accepts one chord string or an array of chord strings. An empty string or array disables the action. A chord uses modifier names followed by one browser KeyboardEvent.code.

toml
[window_manager.shortcuts]
"window.focus.left" = ["control+ArrowLeft", "alt+KeyH"]
"window.tile.bottom" = ""

Indexed action families accept range bindings. Array members may also be ranges:

toml
[window_manager.shortcuts]
"desktop.switch" = ["control+Digit1..9", "meta+Digit1..9"]
"window.tab.jump" = "control+alt+Digit1..8"

The daemon expands ranges before validation. A duplicate anywhere in the complete effective map rejects the whole update; no partial binding is stored.

Use config set with a JSON array for alternates:

Terminal
compozy config set 'window_manager.shortcuts.window.focus.left' \
  '["control+ArrowLeft","alt+KeyH"]'

For workspace-scoped changes, use the command-palette verbs. They update the complete keymap atomically through the daemon. A project keymap is a full copy: it replaces the user keymap for that project. The other window settings inherit per key, so a project shortcut edit stores only the keymap, and a later user change to a setting such as focus_policy still reaches the project:

Terminal
compozy cmd-palette bind window.focus.left control+ArrowLeft --workspace acme
compozy cmd-palette unbind window.focus.left --workspace acme
compozy cmd-palette bindings --workspace acme -o json

When a chord belongs to another command, the daemon names that owner and stores nothing. Add --overwrite to transfer the chord from the named owner.

Configure a global hotkey

The desktop shell can register a global chord for each command from anywhere outside CompozyOS. The daemon owns the intended map under [window_manager.global_shortcuts]; each desktop shell reports whether its chord is active, captured by another application, blocked by permission, or unsupported.

Terminal
compozy cmd-palette bind palette.summon.global meta+shift+Space --global
compozy cmd-palette unbind palette.summon.global --global

A plain browser cannot register these chords and shows requires desktop shell without changing the in-app keymap. Read Global hotkeys for registration states, Accessibility recovery, and platform behavior.

Configure an alias

Aliases are workspace vocabulary for command search. They contain 1–32 characters with no whitespace and are unique within the workspace.

Terminal
compozy cmd-palette alias set session.new new --workspace acme
compozy cmd-palette alias clear session.new --workspace acme

Use --overwrite to transfer an alias already owned by another command. You can also declare aliases in a workspace overlay:

toml
[cmd_palette.aliases]
"session.new" = "new"

Default keymap

meta renders as Command on Apple platforms. A single-primary meta chord maps to Control on other platforms; an explicit control remains Control everywhere.

ActionDefault
palette.open⌘K, ⌘⇧P
palette.view.sessions⌘E
session.new⌘N
scope.global.toggle⌘⇧G
window.nav.back⌘[
session.cycle.previous / session.cycle.next⌃⇧↑ / ⌃⇧↓
session.focus.attention⌃⌥A
workspace.picker⌘⇧O
workspace.cycle.previous / workspace.cycle.next⌘⇧[ / ⌘⇧]
desktop.switch.1 … .9⌃1 … ⌃9
desktop.create⌘⇧N
desktop.overview⌘⇧D
desktop.switch.previous / .next⌃⇧← / ⌃⇧→
window.move_to_desktop.1 … .9Unbound
sidebar.toggle⌘B
window.focus.last⌃⌥O
window.close⌘W
window.tile.left / .right⌃⌥← / ⌃⌥→
window.tile.top / .bottom⌃⌥↑ / ⌃⌥↓
window.unsplitUnbound
window.swap.left / .right / .up / .downUnbound
window.tab.move_left / .move_rightUnbound
window.tab.new⌘T
window.tab.next / .previous⌃Tab / ⌃⇧Tab
window.tab.last⌘9
window.tab.reopen⌘⇧T
window.tab.jump.1 … .8⌘1 … ⌘8
window.focus.left / .right⌃← / ⌃→
window.focus.up / .down⌃↑ / ⌃↓
layout.arrange.two-up / .grid / .main-stackUnbound
layout.arrange.columnsUnbound
layout.balance⌃⌥B
layout.undo / .redo⌘Z / ⌘⇧Z
shortcuts.cheatsheet?, ⌘/

window.tile.left, .right, .top, and .bottom move the focused window to that edge of its tab. window.unsplit is Move to new tab: it takes the focused window out of its split into its own tab. window.swap.left, .right, .up, and .down swap the focused split window with the nearest window shown on that side of its tab; with no window there they do nothing.

Retired in v0.7.0: window.minimize, window.zoom, window.toggle_floating, window.tile.top-left, .top-right, .bottom-left, .bottom-right, window.merge_all, and window.tab.detach. A binding to one of them still loads until v0.8.0 and does nothing; Settings → Layouts → Shortcuts marks the row retired, and resetting it removes the binding.

Press ? outside an editable field, or press ⌘/ anywhere, to open the live keyboard reference. Escape remains a fixed close/focus-return key and is not part of the configurable map.

Terminal preset

Settings → Layouts → Shortcuts can preview and apply this preset as one atomic change. Revert restores the values that those preset keys had immediately before apply. The same block can be pasted into config.toml:

toml
[window_manager.shortcuts]
"window.focus.left" = ["control+ArrowLeft", "alt+KeyH"]
"window.focus.down" = ["control+ArrowDown", "alt+KeyJ"]
"window.focus.up" = ["control+ArrowUp", "alt+KeyK"]
"window.focus.right" = ["control+ArrowRight", "alt+KeyL"]
"window.focus.last" = ["control+alt+KeyO", "alt+KeyO"]
"window.close" = ["meta+KeyW", "alt+KeyW"]
"window.tab.new" = ["meta+KeyT", "alt+KeyT"]
"window.tab.next" = ["control+Tab", "control+alt+KeyL"]
"window.tab.previous" = ["control+shift+Tab", "control+alt+KeyH"]
"window.tab.jump" = "control+alt+Digit1..8"
"window.tab.last" = "control+alt+Digit9"
"session.cycle.next" = ["control+shift+ArrowDown", "control+alt+KeyJ"]
"session.cycle.previous" = ["control+shift+ArrowUp", "control+alt+KeyK"]
"session.focus.attention" = ["control+alt+KeyA", "alt+KeyI"]
"workspace.picker" = ["meta+shift+KeyO", "meta+control+KeyP"]
"workspace.cycle.next" = ["meta+shift+BracketRight", "meta+control+KeyJ"]
"workspace.cycle.previous" = ["meta+shift+BracketLeft", "meta+control+KeyK"]
"desktop.create" = ["meta+shift+KeyN", "meta+control+KeyN"]
"desktop.switch" = ["control+Digit1..9", "meta+Digit1..9"]

The preset moves tab jumps to the Control+Option digit layer. That frees Command digits for desktops and Control+Option J/K for session cycling.

Platform notes

  • Control+digit may switch browser tabs outside the desktop app on non-Apple platforms.
  • Control+Option can alias AltGr on some keyboard layouts. Test the J/K layer before depending on it.
  • ? depends on the current layout's Shift+Slash mapping. ⌘/ is the reliable alternative on non-US layouts.
  • A focused control keeps its own local shortcuts. The keyboard reference marks those rows read-only.