Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sgm1018/BetterWinTab/llms.txt

Use this file to discover all available pages before exploring further.

BetterWinTab stores all user preferences in a single JSON file on disk. Every change made through the Settings panel is serialized immediately — no restart is required. This page documents every field in the AppSettings model, its type, default value, and what it controls.
Settings are persisted to %APPDATA%\BetterWinTab\settings.json. The file is written in camelCase, indented JSON. You can edit it manually while the app is not running; the next launch will load your changes.

​
Settings File Location

%APPDATA%\BetterWinTab\settings.json
On a typical Windows installation this resolves to: 
C:\Users\<YourName>\AppData\Roaming\BetterWinTab\settings.json

​
General Settings

​
hotkeyModifiers
uint
default:"2"
Modifier bitmask for the global activation hotkey. Values: MOD_ALT=0x0001, MOD_CONTROL=0x0002, MOD_SHIFT=0x0004, MOD_WIN=0x0008. Combine by OR-ing values together (e.g. Ctrl + Shift = 0x0006). Default 0x0002 = Ctrl only.
​
hotkeyVKey
uint
default:"9"
Virtual key code for the activation hotkey main key. Default 0x09 = VK_TAB. Common values: 0x20 (Space), 0x0D (Enter), 0x60–0x69 (Numpad 0–9), 0x70–0x7B (F1–F12), 0x41–0x5A (A–Z).
​
showLivePreviews
bool
default:"true"
When true, BetterWinTab renders live DWM thumbnail previews of each open window inside its cards. When false, static process icons are shown instead. Disabling live previews reduces GPU composition overhead on lower-end hardware.
​
thumbnailWidth
int
default:"320"
Width in pixels of each window thumbnail preview card. Applies when showLivePreviews is true.
​
thumbnailHeight
int
default:"200"
Height in pixels of each window thumbnail preview card. Applies when showLivePreviews is true.
​
runAtStartup
bool
default:"false"
When true, BetterWinTab adds itself to the Windows startup registry key HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Run. When false, the registry entry is removed. Toggle this from Settings → General or set it directly in the JSON.
​
hasCompletedOnboarding
bool
default:"false"
Tracks whether the first-run onboarding walkthrough has been completed or explicitly skipped. Once true, the onboarding sequence will not be shown again on subsequent launches.
​
folders
List<WindowFolder>
default:"[]"
The full saved folder configuration — both Smart Folders (auto-populated by process name or window class rules) and manual folders. This list is updated automatically as you create, rename, reorder, or delete folders in the overlay.
​
pinnedWindows
List<PinnedWindowId>
default:"[]"
Windows that are pinned by the user and survive overlay refreshes and reboots. Each entry stores a processName and a titlePattern (supports * wildcards for prefix, suffix, or contains matching). Pinned windows appear first in every folder and are never filtered out.

​
Appearance Settings

​
appearance
AppearanceSettings
default:"(see Themes reference)"
An object containing all 15 semantic color tokens that control every visible color in the BetterWinTab overlay. Colors are stored as hex strings ("#RRGGBB" or "#AARRGGBB" for values with alpha). See the Themes reference for the full token list and default values.
​
customPresets
List<ThemePreset>
default:"[]"
User-saved named theme presets. Each preset has a name string and a full AppearanceSettings snapshot. Custom presets appear alongside the built-in presets in Settings → Themes and can be applied, renamed, or deleted.

​
Clipboard Settings

​
clipboardHistoryEnabled
bool
default:"true"
When true, BetterWinTab listens for clipboard changes and records copied text items into its clipboard history panel. When false, clipboard monitoring is paused and the history panel is hidden. Changing this value while the app is running takes effect immediately.
​
clipboardHistoryMaxItems
int
default:"50"
Maximum number of text entries stored in the clipboard history. Once the limit is reached, the oldest non-pinned item is evicted to make room for a new one.
​
pinnedClipboardItems
List<string>
default:"[]"
Clipboard text entries that have been pinned by the user. Pinned items are never evicted by the rolling history limit and survive application restarts.

​
Example settings.json

Below is a minimal settings file showing the most commonly customized fields: 
{
  "hotkeyModifiers": 2,
  "hotkeyVKey": 9,
  "showLivePreviews": true,
  "thumbnailWidth": 320,
  "thumbnailHeight": 200,
  "runAtStartup": false,
  "clipboardHistoryEnabled": true,
  "clipboardHistoryMaxItems": 50,
  "pinnedClipboardItems": [],
  "pinnedWindows": [],
  "hasCompletedOnboarding": true,
  "customPresets": [],
  "folders": [],
  "appearance": {
    "accentColor": "#39FF14",
    "accentDimColor": "#1A8A0A",
    "accentSubtleColor": "#0D3D06",
    "backgroundColor": "#000000",
    "surfaceColor": "#0A0A0A",
    "cardColor": "#111111",
    "borderColor": "#1A1A1A",
    "textPrimaryColor": "#FFFFFF",
    "textSecondaryColor": "#AAAAAA",
    "textMutedColor": "#666666",
    "dangerColor": "#FF3344",
    "folderHoverColor": "#1A39FF14",
    "folderSelectedColor": "#2939FF14",
    "windowHoverBorderColor": "#6639FF14",
    "windowHoverBackgroundColor": "#0C39FF14"
  }
}
If settings.json is missing or unreadable, BetterWinTab silently falls back to all defaults on startup and writes a fresh file the first time you save any setting.

Build docs developers (and LLMs) love

Get started for freeTalk to us