Config reference

Every key accepted in ~/.config/bettercmdtab/config.json and in exported settings files. Keys are listed without the Switcher. prefix, which is how they are written.

All keys are optional. Omitting one keeps its current value — see partial edits. Numbers outside the range shown are clamped rather than rejected, and an unrecognised string falls back to the key's default.

The three array-of-objects keys are documented separately: appExceptions, scopedShortcutList and shortcutOverrides.

This page is generated from the same schema.json the app writes next to your config file, so types, descriptions and allowed values are the app's own. Your editor shows the identical information inline.

Display & timing

Where the panel opens and how quickly it reacts.

Key	Type	Default	Description
`displayMode`	`string`	`"mouseCursor"`	Which monitor the switcher opens on. `"mouseCursor"` — Monitor with the cursor `"activeWindow"` — Monitor with the active space `"mainDisplay"` — Main display
`revealDelayMs`	`integer` 40…500	`100`	How long the shortcut must be held before the panel appears — a quicker tap switches without showing it (milliseconds).
`titleRefreshIntervalMs`	`integer` 50…2000	`200`	Delay before window titles in the open switcher catch up after an app renames one (milliseconds). Lower reacts sooner, higher costs less CPU.

Layout

Which layout the switcher uses and how big it is.

Key	Type	Default	Description
`layoutMode`	`string`	`"iconDock"`	Switcher layout: list rows, an icon grid, or window previews. `"list"` — List `"iconDock"` — Grid View `"windowPreview"` — Previews
`panelScalePercent`	`integer` 50…150	`120`	Overall size of the switcher panel, in percent.
`listWidthPercent`	`integer` 30…100	`100`	Width of list rows as a percentage of the automatic, screen-scaled width.
`gridMaxColumns`	`integer` 0…12	`0`	Column cap for the grid layout. 0 = automatic (as many as fit).

Appearance

Colour, blur, corners and typography of the panel.

Key	Type	Default	Description
`panelAppearance`	`string`	`"system"`	Light or dark switcher, independent of the rest of macOS. `"system"` — System `"light"` — Light `"dark"` — Dark
`panelOpacity`	`integer` 30…100	`100`	Opacity of the panel background, in percent.
`panelCornerRadius`	`integer` -1…40	`0`	Panel corner radius in points. 0 = automatic (follows the panel size), -1 = square corners.
`backdropMaterial`	`string`	`"hud"`	Blur material behind the rows. Ignored by the macOS 26 glass backdrop. `"hud"` — HUD (default) `"sidebar"` — Sidebar `"menu"` — Menu `"popover"` — Popover `"fullScreen"` — Full Screen `"underWindow"` — Under Window
`fontScale`	`string`	`"standard"`	Size of the name/title text, independent of the panel scale. `"extraSmall"` — Extra small `"small"` — Small `"standard"` — Default `"large"` — Large `"extraLarge"` — Extra large
`fontFace`	`string`	`"system"`	Typeface used for names and titles. `"system"` — System `"rounded"` — Rounded `"serif"` — Serif `"monospaced"` — Monospaced
`boldSelectedLabel`	`boolean`	`true`	Show the highlighted entry's title in bold.
`showApplicationNames`	`boolean`	`true`	Show application names next to the icons.
`showWindowTitleLabel`	`boolean`	`true`	Show each window's title, not just its app.
`previewTitleAlignment`	`string`	`"center"`	Where the title sits under each window-preview tile. `"leading"` — Left `"center"` — Center `"trailing"` — Right
`titleTruncationMode`	`string`	`"tail"`	Which part of a too-long title is replaced by an ellipsis. `"head"` — Beginning `"middle"` — Middle `"tail"` — End

Which apps and windows the switcher lists, and in what order.

Key	Type	Default	Description
`sortOrder`	`string`	`"mru"`	Order apps and windows are listed in. `"mru"` — Most recent `"mruWindows"` — Most recent (windows) `"alphabetical"` — Alphabetical `"launchOrder"` — Launch order
`spaceScope`	`string`	`"allSpaces"`	Which Spaces windows are pulled from. `"allSpaces"` — All Spaces `"currentSpace"` — Current Space `"visibleSpaces"` — Visible Spaces
`applicationsOnly`	`boolean`	`false`	Show one entry per app instead of one per window.
`windowDrillEnabled`	`boolean`	`true`	Peek the highlighted app's windows with ↓ while "applications only" is on.
`showMinimizedWindows`	`boolean`	`true`	Include minimized windows.
`showHiddenApps`	`boolean`	`true`	Include apps hidden with ⌘H.
`sinkHiddenApps`	`boolean`	`true`	Move hidden apps to the bottom of the list instead of leaving them in place.
`showWindowlessApps`	`boolean`	`true`	Include running apps that have no open window.
`showUnreadBadges`	`boolean`	`true`	Show each app's Dock unread badge on its entry.
`showRecentlyClosed`	`boolean`	`false`	Offer recently closed apps in search so they can be reopened.
`recentlyClosedLimit`	`integer` 0…50	`5`	How many recently closed apps to offer. 0 disables them.
`pinnedBundleIDs`	`array`	`[]`	Bundle IDs pinned to the front of the switcher, in the order they appear.
`hideAllExcludedBundleIDs`	`array`	`[]`	Bundle IDs the "hide all windows" shortcut leaves visible.

Tabs

How browser and native tabs appear in the list.

Key	Type	Default	Description
`tabDrillEnabled`	`boolean`	`true`	Peek the highlighted window's tabs with \.
`expandTabsAsWindows`	`boolean`	`false`	List native system tabs (Finder, Terminal, TextEdit, …) as separate entries.
`expandBrowserTabsAsWindows`	`boolean`	`false`	List browser tabs (Safari, Chromium) as separate entries.
`browserTabRowLimit`	`integer` 0…16	`0`	Cap on tab entries per browser window. 0 = unlimited; anything else is taken as 2…16.
`showBrowserIconOnTabs`	`boolean`	`false`	Badge each browser-tab entry's favicon with the source browser's icon.

Search

Type-to-filter and letter-jump behaviour.

Key	Type	Default	Description
`fuzzySearchEnabled`	`boolean`	`true`	Type to filter the switcher.
`fuzzySearchRankBestMatchFirst`	`boolean`	`false`	Sort search results by match quality instead of keeping the list order.
`searchIncludesLaunchableApps`	`boolean`	`true`	Include installed apps that aren't running, so search can launch them.
`searchExpandsBrowserTabs`	`boolean`	`false`	Search browser tab titles too.
`searchDismissMode`	`string`	`"holdModifier"`	Whether searching keeps the switcher open after the modifier is released. `"holdModifier"` — Hold ⌘ `"stayOpen"` — Stay open until I choose
`letterHintsEnabled`	`boolean`	`true`	Show the letter that jumps to each entry.
`letterChainTimeoutMs`	`integer` 200…3000	`1000`	How long a typed letter-jump prefix stays active before it expires (milliseconds).

Keyboard

What happens while the shortcut is held, and how stepping works.

Key	Type	Default	Description
`stayOpenOnRelease`	`boolean`	`false`	Keep the switcher open after the modifier is released.
`stayOpenOnQuickTap`	`boolean`	`false`	Also keep it open after a quick tap of the shortcut.
`shiftTapStepsBackward`	`boolean`	`true`	Tap Shift while switching to step backwards.
`backtickReversesAppSwitching`	`boolean`	`false`	Use the window-switch shortcut (⌘`) to step backwards through apps.
`vimNavigationEnabled`	`boolean`	`false`	Navigate with h/j/k/l as well as the arrow keys.

Mouse & hover

Pointer selection and the inline action buttons.

Key	Type	Default	Description
`scrollToSwitch`	`boolean`	`true`	Move the selection by scrolling.
`scrollReverseDirection`	`boolean`	`false`	Reverse the scroll direction.
`clickOutsideToDismiss`	`boolean`	`true`	Click outside the panel to dismiss it without switching.
`mouseHoverSelectionEnabled`	`boolean`	`true`	Highlight the entry under the pointer.
`mouseClickSelectionEnabled`	`boolean`	`true`	Click an entry to switch to it.
`hoverActionsEnabled`	`boolean`	`false`	Show action buttons on the entry under the pointer.
`hoverShowClose`	`boolean`	`true`	Include "close" among the hover actions.
`hoverShowMinimize`	`boolean`	`true`	Include "minimize" among the hover actions.
`hoverShowMaximize`	`boolean`	`true`	Include "maximize" among the hover actions.
`hoverShowHide`	`boolean`	`true`	Include "hide app" among the hover actions.
`hoverShowQuit`	`boolean`	`true`	Include "quit" among the hover actions.
`hoverShowForceQuit`	`boolean`	`false`	Include "force quit" among the hover actions.

Window management

Behaviour of the tiling shortcuts.

Key	Type	Default	Description
`cycleTileWidths`	`boolean`	`false`	Repeating the tile-left/right shortcut cycles the window through half → two-thirds → one-third width.

Shortcuts

The key combinations themselves are recorded outside this file. Scoped shortcuts and per-shortcut overrides are documented on their own pages.

Key	Type	Default	Description
`directActivationBindings`	`array` exactly 9 items	`["", "", "", "", "", "", "", "", ""]`	Bundle ID activated by each direct-activation slot, in slot order. An empty string leaves the slot unused.
`nextScopedShortcutID`	`integer`		Internal counter for allocating scoped-shortcut ids. Never decreases, so a removed id is never reused. Don't edit.

Sound, haptics, the menu-bar icon and screen-sharing privacy.

Key	Type	Default	Description
`hideMenuBarIcon`	`boolean`	`false`	Hide the menu-bar icon.
`hapticOnCommit`	`boolean`	`false`	Tap the trackpad when the switcher commits a selection.
`soundOnCommit`	`boolean`	`false`	Play a sound when the switcher commits a selection.
`commitSoundName`	`string`	`"Tink"`	macOS system sound played on commit. A custom sound file stays on the Mac that chose it. `"Basso"` `"Blow"` `"Bottle"` `"Frog"` `"Funk"` `"Glass"` `"Hero"` `"Morse"` `"Ping"` `"Pop"` `"Purr"` `"Sosumi"` `"Submarine"` `"Tink"`
`hideFromScreenSharing`	`boolean`	`false`	Keep the switcher panel out of screen recordings and shared screens.

Experimental

Off by default and matching the Experimental settings pane. These can change or disappear between releases.

Key	Type	Default	Description
`experimentalSwipeTrigger`	`boolean`	`false`	Three-finger trackpad swipe.
`swipeMode`	`string`	`"openSwitcher"`	What the three-finger swipe does. `"openSwitcher"` — Open switcher `"switchSpaces"` — Switch Spaces `"quickSwitch"` — Quick switch (last 2 apps)
`swipeReverseDirection`	`boolean`	`false`	Reverse the swipe direction.
`swipeCommitOnRelease`	`boolean`	`false`	Commit the swipe selection when the fingers lift.
`swipeSensitivity`	`integer` 1…10	`5`	How far fingers must slide to advance one app. Higher = more sensitive.
`experimentalInstantSpaceSwitch`	`boolean`	`false`	Switch Spaces without the macOS animation.
`experimentalBrowserTabMRU`	`boolean`	`false`	Track browser tabs in the recency order.
`experimentalBrowserTabPreviews`	`boolean`	`false`	Show thumbnails for browser tabs.
`experimentalLivePreviews`	`boolean`	`false`	Keep window previews refreshing while the panel is open. Costs CPU/GPU.

Legacy

Superseded keys — always set the replacement named in the description instead. Only panelSize is migrated and then deleted; currentSpaceOnly and scopedShortcutScopes are still written on every change so older builds reading the same file stay consistent, so expect to see them; excludedBundleIDs and experimentalUnreadBadges are read at most once and never removed.

Key	Type	Description
`panelSize`	`string`	Legacy size preset, migrated to panelScalePercent at launch. Use panelScalePercent instead. `"small"` `"standard"` `"large"`
`currentSpaceOnly`	`boolean`	Legacy "only the current Space" flag, kept in sync with spaceScope for older builds. Edit spaceScope instead.
`excludedBundleIDs`	`array`	Legacy always-hidden bundle IDs, folded into appExceptions at launch. Edit appExceptions instead.
`experimentalUnreadBadges`	`boolean`	Legacy unread-badge flag, read once to seed showUnreadBadges. Edit showUnreadBadges instead.
`scopedShortcutScopes`	`array` exactly 3 items	Legacy fixed scoped-shortcut slots, migrated to scopedShortcutList. Edit scopedShortcutList instead.