Keybindings

Magia has a built-in command registry. Every command has an ID, a category, a context, and an optional default key binding. Commands can be triggered from the Command Palette or via their keyboard shortcut.

Command Palette

Open the Command Palette with Cmd+K (macOS) / Ctrl+K (Linux/Windows). It shows all registered commands and lets you search and execute them by name. Commands that have a keybinding display it on the right side of the palette.

Default Keybindings

Commands

Command	ID	Default Binding	Context
Command Palette	`app.command-palette`	`Cmd+K`	Global
Open Settings	`app.settings`	`Cmd+,`	Global
New Session	`app.new-session`	`Cmd+N`	Global

Editor

These bindings are active when focus is inside the editor panel.

Command	ID	Default Binding	Context
Save File	`editor.save`	`Cmd+S`	Editor
Undo	`editor.undo`	`Cmd+Z`	Editor
Redo	`editor.redo`	`Cmd+Shift+Z`	Editor
Find	`editor.find`	`Cmd+F`	Editor
Find and Replace	`editor.replace`	`Cmd+H`	Editor

Terminal

Command	ID	Default Binding	Context
Toggle Terminal	`terminal.toggle`	Cmd+`	Global
Clear Terminal	`terminal.clear`	`Cmd+K`	Terminal

Command	ID	Default Binding	Context
Go Home	`nav.go-home`	`Cmd+Shift+H`	Global
Go Back	`nav.go-back`	`Cmd+[`	Global

Contexts

Context	Active when
`global`	Always active throughout the app.
`editor`	The CodeMirror editor panel has keyboard focus.
`terminal`	The xterm.js terminal panel has keyboard focus.

Commands in the global context fire regardless of which panel is focused. Context-specific commands only fire when the relevant panel is active.

Customizing Keybindings

Via the Settings UI

Open Settings (Cmd+,).
Navigate to Keybindings.
Click the binding you want to change, then press the new key combination.
Changes take effect immediately and are persisted automatically.

To reset a single binding to its default, click the reset icon next to it. To reset all bindings, use the Reset All button at the top of the keybindings panel.

Via keybindings.json

Custom bindings are stored alongside settings in the app data directory. You can also edit them directly:

macOS:

~/Library/Application Support/sh.magia.com/keybindings.json

The file is a JSON object mapping command IDs to key combo objects:

{
  "app.new-session": {
    "key": "n",
    "meta": true,
    "ctrl": false,
    "shift": true,
    "alt": false
  }
}

Field	Type	Description
`key`	`string`	The key name (e.g. `"k"`, `"F1"`, `"Escape"`, `","`, `"`”`).
`meta`	`boolean`	`Cmd` (macOS) / `Win` (Windows/Linux).
`ctrl`	`boolean`	`Ctrl`.
`shift`	`boolean`	`Shift`.
`alt`	`boolean`	`Alt` / `Option`.

Restart is not required — the store picks up changes on next launch.

Command Registry System

Magia uses a Zustand-based command registry (src/store/keybindings.ts). Commands are registered at app startup via registerDefaultCommands(). Plugins and feature modules can add their own commands by calling registerCommand() at any time.

import { useKeybindingsStore } from "@/store/keybindings";

useKeybindingsStore.getState().registerCommand({
  id: "myfeature.do-thing",
  label: "Do the Thing",
  category: "My Feature",
  context: "global",
  defaultBinding: { key: "t", meta: true, ctrl: false, shift: false, alt: false },
});

Key APIs:

Function	Description
`registerCommand(cmd)`	Register a new command. No-op if the ID already exists.
`getEffectiveBinding(id)`	Returns the active binding (custom override or default).
`setCustomBinding(id, combo)`	Store a custom binding for a command.
`resetBinding(id)`	Remove the custom override, reverting to the default.
`resetAllBindings()`	Remove all custom overrides.
`detectConflicts(excludeId, combo, context, ...)`	Check if a combo conflicts with another command in the same context.