Global config

Two files under ~/.shelbi/ hold hub-wide settings that apply across every project on your machine, independent of any single project's config mode: config.yaml (UI preferences) and keys.yaml (keybindings). Both are optional: absent or partial files fall back to built-in defaults, never an error.

config.yaml

Per-user UI preferences. Distinct from shelbi.yaml (the per-project last_launched index) so a future shelbi config reset can wipe UI tweaks without touching hub bookkeeping. A file that omits a key or a block resolves to that setting's default.

A new install starts from a self-documenting config.yaml that sets theme: dark, desktop.contrast: 50, and a translucent desktop window (desktop.window_opacity: 85 and desktop.window_blur: 30). Whichever writes the file first (shelbi init, or a first settings change in either client) writes those values, and with no file at all both clients show them. An existing config.yaml is never rewritten: without these keys it keeps the defaults in the tables below (auto, contrast 0, an opaque window).

Path: ~/.shelbi/config.yaml

# ~/.shelbi/config.yaml
editor: code --wait
theme: light
desktop:
  contrast: 50
  window_opacity: 85
  window_blur: 30

Editor and diff tool

editor and diff_tool each take one of two forms. The rule is the same for both: a command-line tool opens as a pane (a terminal in the worktree, beside the agent), and an app opens in the app.

# ~/.shelbi/config.yaml
 
# A command: a program on your login PATH, with flags if you like.
editor: hx
diff_tool: difft
 
# An app: the path to its .app bundle.
editor: { app: /Applications/Zed.app }
diff_tool:
  app: /Applications/Kaleidoscope.app

A plain string is a command, so a config.yaml written before apps were supported keeps working unchanged.

Editor. A command runs in a pane in the worktree (exec <command>). An app opens the worktree with open -a <app> <worktree>, and "Edit in" leaves the current view selected rather than switching to a pane. Unset, Shelbi runs $EDITOR, then vim. A pane can't host an app, so anything that needs a terminal editor falls back past an app setting to $EDITOR, then vim.

Diff tool. View Diff compares the branch with its base (merge-base(<base branch>, HEAD)..HEAD). In precedence order it shows:

1. the project's review.diff_command, when it sets one,
2. diff_tool, when set to a tool,
3. Shelbi's own diff view, which is what diff_tool: builtin asks for and what an unset setting means.

diff_tool: git runs git's own difftool (diff.guitool, else diff.tool). Any other diff_tool command runs in a pane through git difftool, one file at a time, with the two files appended (nvim -d, vimdiff). A command that names $LOCAL and $REMOTE itself is run as written. difft (difftastic) runs as git's external diff through less -R.

A diff_tool app opens the diff in the app through its own command-line helper, found on your login PATH or inside the app bundle:

Any other app gets the two folders with open -W -a <app>. If a listed app's helper isn't installed, View Diff says so on the status line.

Remote workspaces. Shelbi's own diff view reads a worktree on any machine, in both clients. A workspace on another machine also offers Edit, and an external diff tool, as panes that run on that machine. An app can't open a worktree on another machine. A review slot on another machine offers no Edit, and offers View Diff only for Shelbi's own view.

Labels. "Edit in <name>" uses the tool's name: Edit in Neovim for nvim, Edit in Helix for hx, Edit in Visual Studio Code for code --wait or the app, and the bundle's name for any other app. A command Shelbi doesn't know shows its program name with the first letter upper-cased.

Settings. Settings ▸ General has an Editor picker and a Diff tool picker in both clients. Each lists the default (no setting, so the fallback applies), the command-line tools and the apps Shelbi finds installed, Browse… (an app or a program on disk), and Other command… (a command line with its flags, saved when you press Enter). A pick saves at once, and the page shows what Shelbi runs and where it comes from (this key, $EDITOR, or the vim default). In the TUI, Browse asks for a path, with Tab completion.

Theme

theme picks the color theme both clients use. The two themes share one set of named colors, so the TUI and the desktop app look like the same product.

Both clients set it in Settings ▸ General. In the TUI a change saves at once and repaints every surface on the next frame, with no restart and no effect on running sessions. The TUI also reads config.yaml again whenever its Settings opens, so an edit made in a text editor or in the desktop app shows there. A missing key is auto (a new install's file sets dark). The dark theme follows your terminal's own palette for its status colors; the light theme pins every color, so it reads the same in any light terminal.

Desktop

The desktop: block holds the desktop app's settings. Its Settings ▸ General and Settings ▸ Terminal pages write these keys for you; every one is optional.

zen_toggle chords

The accepted values for the Zen toggle chord:

keys.yaml

Overrides for Shelbi's keybindings, shared by the TUI and the desktop app. Both clients edit this file in Settings ▸ Keybindings (in the TUI press , in the sidebar, then 2; in the desktop app, ⌘2 while Settings is open). Built-in chords apply out of the box; this file layers on top of them, either globally (defaults) or per project (projects.<name>). Parse errors never fail the load. A mistyped entry is skipped and that action keeps its built-in chord.

Path: ~/.shelbi/keys.yaml

Shape

# ~/.shelbi/keys.yaml
defaults:                 # applies to every project
  <mode>:
    <action>: <chord | [chords] | null>
projects:                 # per-project overrides, keyed by project name
  <project-name>:
    <mode>:
      <action>: <chord | [chords] | null>

Bindings resolve in three layers, each overriding the last: built-in defaults → defaults.<mode>.<action> → projects.<name>.<mode>.<action>.

Leaf values

The value under each action is untyped so one bad entry only affects itself:

In the diff mode a chord can be two keys, separated by a space ('g g', 'z C', '] h'). Quote them: a bare ] isn't YAML. A key can't both do something by itself and start a two-key binding.

Modes

The valid top-level keys under defaults and each projects.<name>:

global, sidebar, kanban, popover, activity, diff, palette.

global bindings apply everywhere; the rest scope to their pane.

Actions

The action names accepted under each mode, with their built-in chords:

Most modes also carry refresh (r) and scroll-navigation actions (page_up/page_down, scroll_home). For the full list with the chords in effect after your keys.yaml, run shelbi config list-actions. shelbi config dump-keybindings prints the whole default keymap as a starting keys.yaml, and shelbi config check validates the file and reports errors and warnings.

A mode binding that reuses a global chord is dead in the sidebar, kanban, and activity modes: global bindings fire first. shelbi config check warns about it. The diff mode is the other way around: its bindings win while the diff view has focus, so ctrl-p opens its file palette there.

# rebind the palette opener globally, and add a second chord in one project
defaults:
  global:
    open_palette: ctrl-k
projects:
  myapp:
    kanban:
      move_card_left: [H, alt-h]

Sibling files

Two more files live under ~/.shelbi/ but are managed by Shelbi rather than hand-edited:

• shelbi.yaml — hub-wide bookkeeping: a per-project last_launched index used by the project picker. Written when you launch a project.
• events.log — the cross-project events log. Append-only state, not config.

See also

• Config modes — per-project config, which these hub-wide files sit above.
• Project config — the per-project YAML.