Customizing

Plugins are for the things Dispatch does not own. This is the same idea for the things it does.

A customization is a folder with a customize.json in it. Nothing in it runs, which is the difference from a plugin: a plugin is code executed in a sandbox with a capability list, while a customization is data, and every value in it is checked against a closed list before it reaches a stylesheet, a keymap or a terminal.

%APPDATA%\Dispatch\customize\<id>\customize.json     ← yours
<install dir>\customize\<id>\customize.json          ← shipped

Same two folders as plugins and the same order: a folder in your profile shadows one bundled with the app. Customize ▸ Open folder makes the first one and opens it. Saving a file in there reloads it: the folder is watched, by the same watcher a document tile uses.

Nothing changes until you ask it to

No theme is picked until somebody picks one, and a fresh profile carries no customization key at all, so an upgraded install looks exactly like a new one.

The bundled default customization is Dispatch’s own colours written out: the worked example to read, and the way back. Picking it moves nothing on screen, because it matches the app’s own stylesheet and terminal theme value for value.

What a manifest may say

{
  "id": "midnight",          // folder name must match; [a-z0-9-]
  "name": "Midnight",
  "version": "1.0.0",
  "apiVersion": 1,

  // At least one of these five, or the file is refused —
  // a folder that customizes nothing is one somebody did not finish.
  "theme": { },
  "terminal": { },
  "actions": [ ],
  "keys": { },
  "layout": { }
}

An unknown top-level key is rejected, not ignored, and so is an unknown theme token, an unknown terminal colour and a keys entry naming a command that does not exist. A token spelled acccent fails the file rather than quietly doing nothing. Whatever failed is listed at the top of the Customize screen, on every tab, with its reason.

theme

The interface’s own colour tokens, keyed by name: bg, panel, panel-2, border, border-soft, text, text-strong, muted, muted-2, accent, accent-dim, green, amber, red, gold, plus two lengths, radius and sidebar-width, and two font stacks, mono and ui.

A colour is #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(…) or rgba(…). A length is a number and a unit. There is no calc().

terminal

xterm’s palette, spelled the way xterm spells it: background, foreground, cursor, cursorAccent, selectionBackground, the eight ANSI colours, their eight bright counterparts, and the three scrollbar entries.

A theme that names half of them puts the other half back rather than leaving whatever the last theme said.

actions: your own buttons

A named command, where it runs, and where its button appears.

"actions": [
  {
    "id": "test",
    "label": "Run tests",
    "command": "cargo test --workspace",
    "where": ["sidebar", "tile", "palette"],
    "project": "D:\\code\\dispatch",   // optional
    "submit": true                     // optional
  }
]

Where it lands, in order of how specific the answer is: an action with a project opens a terminal there and seeds it; one pressed on a tile header goes to that tile; anything else goes to the terminal you are in. With nothing to send it to, it opens a terminal exactly as ＋ New terminal does and seeds that.

"submit": false types the command and stops, leaving it at the cursor, the same way an armed tile does.

The three places: sidebar mounts into the plugin dock above the MCP button, tile adds a button beside Clear and Restart, and palette adds a row to the box Ctrl+Shift+P opens.

keys: the keymap

"keys": {
  "palette.open": "Ctrl+Alt+J",
  "action:test": "Ctrl+Alt+T",
  "docs.open": ""                // empty takes the key away
}

The bindable commands are the ones the window itself owns: palette.open, docs.open, deck.open, customize.open, search.focus, broadcast.focus, terminal.new, sidebar.toggle, topbar.toggle, workspace.next, workspace.prev, font.increase, font.decrease, font.reset, plus action:<id> for an action in the same file.

A shortcut needs Ctrl, Alt or Super and one other key. Shift on its own is not enough: Shift+A is a capital A, and the broadcast bar needs to receive it as one.

Three layers, last writer wins: the defaults, then every enabled customization, then whatever you set on the Keys tab. A chord two commands want is a conflict, and the screen says so in red and names which one actually happens.

Menu accelerators (Ctrl+, for Settings, F11, the zoom trio) belong to the native menu bar rather than to the keymap, and are not bindable here. Everything else is on Keyboard and quick open.

layout

"layout": {
  "columns": 2,        // 1–4
  "tileHeight": 340,   // 180–760
  "panels": { "sidebar": true, "topbar": true, "pluginBar": true, "activityChip": true }
}

Applied once, when you press Apply layout on the Layout tab. Nothing here keeps enforcing itself behind somebody who then drags a tile. columns and tileHeight are what a new workspace starts from; the Cols row and the Height slider in the top bar are what change the workspace you are on.

Workspace presets

The Layout tab also holds presets: a saved shape for a workspace, meaning its columns, its tile height, and which projects are open in it.

Applying one opens what is missing rather than closing what is there. Nothing already in the workspace is closed for you.

Open on launch applies a preset only when Dispatch starts with nothing to restore. A session that had terminals in it gets those back instead.