Dokumentacja konfiguracji

Każdy klucz config.json — typ, wartość domyślna, akceptowany zakres i dozwolone wartości.

Wszystkie klucze akceptowane w ~/.config/bettercmdtab/config.json i w eksportowanych plikach ustawień. Klucze są wymienione bez prefiksu Switcher., ponieważ właśnie w taki sposób są zapisywane.

Wszystkie klucze są opcjonalne. Pominięcie klucza zachowuje jego bieżącą wartość — zobacz częściowe zmiany. Liczby spoza podanego zakresu są ograniczane zamiast odrzucane, a nierozpoznany ciąg znaków powoduje powrót do wartości domyślnej klucza.

Trzy klucze będące tablicami obiektów opisano osobno: appExceptions, scopedShortcutList i shortcutOverrides.

Ta strona jest generowana z tego samego pliku schema.json, który aplikacja zapisuje obok pliku konfiguracyjnego, dlatego typy, opisy i dozwolone wartości pochodzą bezpośrednio z aplikacji. Edytor pokazuje te same informacje w tekście. Opisy kluczy i etykiety dozwolonych wartości pozostają obecnie po angielsku, ponieważ pochodzą z angielskiego pliku schematu generowanego przez aplikację.

Ekran i czas

Gdzie otwiera się panel i jak szybko reaguje.

Klucz	Typ	Wartość domyślna	Opis
`displayMode`	`string`	`"mouseCursor"`	Which monitor the switcher opens on. `"mouseCursor"` — Monitor with the cursor `"activeWindow"` — Monitor with the active app `"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.

Układ

Jakiego układu używa przełącznik i jaki ma rozmiar.

Klucz	Typ	Wartość domyślna	Opis
`layoutMode`	`string`	`"iconDock"`	Switcher layout: list rows, an icon grid, or window previews. `"list"` — List `"iconDock"` — Grid View `"windowPreview"` — Previews
`panelScalePercent`	`integer` 35…150	`100`	Overall size of the switcher panel, in percent. 100% matches the macOS switcher.
`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).
`gridSingleRow`	`boolean`	`true`	Keep the grid on one row, shrinking the icons to fit, instead of wrapping. Ignored while gridMaxColumns caps the columns.

Wygląd

Kolor, rozmycie, narożniki, typografia i przechwytywanie podglądów panelu.

Klucz	Typ	Wartość domyślna	Opis
`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
`animationsEnabled`	`boolean`	`true`	Glide the panel, the tiles and the tab strip between states. Off, or with macOS Reduce Motion on, every change is a hard cut.
`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.
`showWindowStatusIcons`	`boolean`	`true`	Show the hidden, minimized, full-screen and no-window glyphs on each entry.
`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
`browserTabPreviews`	`boolean`	`false`	Show thumbnails for browser tabs in the Previews layout.
`livePreviews`	`boolean`	`false`	Keep window previews refreshing while the panel is open. Costs CPU/GPU; needs macOS 14 or later.

Zawartość

Które aplikacje i okna wyświetla przełącznik, w jakiej kolejności i jak przechodzi do wybranego.

Klucz	Typ	Wartość domyślna	Opis
`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
`instantSpaceSwitch`	`boolean`	`false`	Switch Spaces without the macOS animation.
`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.
`sinkMinimizedWindows`	`boolean`	`true`	Move minimized windows to the bottom of the list instead of leaving them in their most-recently-used position.
`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.

Karty

Jak karty przeglądarek i karty natywne pojawiają się na liście.

Klucz	Typ	Wartość domyślna	Opis
`tabDrillEnabled`	`boolean`	`true`	Peek the highlighted window's tabs with the Peek tabs key.
`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.
`browserTabMRU`	`boolean`	`false`	Track browser tabs in the recency order.

Wyszukiwanie

Filtrowanie podczas pisania i przechodzenie po literach.

Klucz	Typ	Wartość domyślna	Opis
`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).

Klawiatura

Co dzieje się podczas przytrzymywania skrótu i jak działa przechodzenie między pozycjami.

Klucz	Typ	Wartość domyślna	Opis
`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.

Mysz i wskazywanie

Wybieranie wskaźnikiem i przyciski szybkich działań.

Klucz	Typ	Wartość domyślna	Opis
`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.

Zarządzanie oknami

Działanie skrótów układania okien.

Klucz	Typ	Wartość domyślna	Opis
`cycleTileWidths`	`boolean`	`false`	Repeating the tile-left/right shortcut cycles the window through half → two-thirds → one-third width.

Skróty

Same kombinacje klawiszy są zapisywane poza tym plikiem. Skróty zakresowe i ustawienia poszczególnych skrótów opisano na osobnych stronach.

Klucz	Typ	Wartość domyślna	Opis
`directActivationBindings`	`array` dokładnie 9 elementów	`["", "", "", "", "", "", "", "", ""]`	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.

Dźwięk, haptyka, ikona paska menu i prywatność udostępniania ekranu.

Klucz	Typ	Wartość domyślna	Opis
`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.

Przesunięcie po gładziku

Gest trzema palcami na gładziku i jego zachowanie. Domyślnie wyłączony; włączysz go w Skróty › Przesunięcie po gładziku. Te opcje mogą się zmienić lub zniknąć między wydaniami.

Klucz	Typ	Wartość domyślna	Opis
`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.

Przestarzałe

Zastąpione klucze — zawsze ustawiaj zamiennik wskazany w opisie. Tylko panelSize jest migrowany, a następnie usuwany; currentSpaceOnly, scopedShortcutScopes, experimentalBrowserTabMRU, experimentalInstantSpaceSwitch, experimentalBrowserTabPreviews i experimentalLivePreviews nadal są zapisywane przy każdej zmianie, aby starsze wersje korzystające z tego samego pliku zachowały spójność, więc licz się z ich obecnością w pliku. excludedBundleIDs i experimentalUnreadBadges są odczytywane jako wartości zapasowe tylko przy starcie i nigdy nie są usuwane.

Klucz	Typ	Opis
`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.
`experimentalBrowserTabMRU`	`boolean`	Legacy browser-tab recency flag, kept in sync with browserTabMRU for older builds. Edit browserTabMRU instead.
`experimentalInstantSpaceSwitch`	`boolean`	Legacy instant-Space-switch flag, kept in sync with instantSpaceSwitch for older builds. Edit instantSpaceSwitch instead.
`experimentalBrowserTabPreviews`	`boolean`	Legacy browser-tab-preview flag, kept in sync with browserTabPreviews for older builds. Edit browserTabPreviews instead.
`experimentalLivePreviews`	`boolean`	Legacy live-preview flag, kept in sync with livePreviews for older builds. Edit livePreviews instead.
`scopedShortcutScopes`	`array` dokładnie 3 elementów	Legacy fixed scoped-shortcut slots, migrated to scopedShortcutList. Edit scopedShortcutList instead.

Inne

Klucze obecne w schemacie, ale jeszcze nieprzypisane do sekcji dokumentacji.

Klucz	Typ	Wartość domyślna	Opis
`selectionColor`	`string`		Color of the selection highlight and the quick-jump letters. "transparent" (the default) leaves the highlight colorless and tints only the quick-jump letters; "system" follows the macOS accent; "custom" uses selectionColorHex. `"transparent"` — Transparent `"system"` — macOS accent `"blue"` — Blue `"purple"` — Purple `"pink"` — Pink `"red"` — Red `"orange"` — Orange `"yellow"` — Yellow `"green"` — Green `"graphite"` — Graphite `"custom"` — Custom…
`selectionColorHex`	`string`		Selection color used when selectionColor is "custom", as #RRGGBB. Falls back to the macOS accent when absent or malformed.