Settings Reference

Start BetterStage automatically when you log in to macOS. Uses the native SMAppService launch-at-login mechanism.

Choose the language BetterStage uses: English or one of 18 translations. Reopening the app applies the change.

Automatically switch to a stage when one of its windows gains focus. For example, if you click a window that belongs to Stage 2 while Stage 1 is active, BetterStage switches to Stage 2 automatically.

Moving the cursor to the center section of the top edge reveals the stages bar. Useful if you prefer mouse-driven stage switching or drag-and-drop stage assignment.

After a completed stage switch, show a click-through Stages Bar indicator for about 1.5 seconds so you can confirm the new stage without interacting with it. Find it under Settings > Stages > Stages Bar.

On built-in Mac displays with a notch, this optional setting keeps the top-edge Stages Bar trigger from firing inside the notch area. The rest of the top edge still opens the Stages Bar normally.

How long the cursor needs to rest at a screen edge before the hot edge fires (0.0 – 2.0 seconds). Increase if you keep triggering edges by accident while moving windows; drop it to zero for instant activation.

When you send a window to another stage, BetterStage also switches to that stage automatically.

When an App Routing rule sends a new window to its designated stage, BetterStage switches to that stage so you see the window immediately. Turn this off to route windows silently — a toast will appear showing where the window went.

Hold the Option key and scroll with your mouse or trackpad to cycle through stages. Scroll up for the previous stage, down for the next.

Keeps Cmd+` cycling scoped to windows from the current app that are on the active stage, instead of cycling through every window for that app across all stages.

Choose which status items BetterStage shows, then drag them into any order: the BetterStage logo, Stage index, total window count, Stage name, and Window Modes. BetterStage always keeps at least one item enabled so the menu remains accessible.

The Stage index supports Current/Total (for example, 3/7), Index Stepper, and Index Only. The Window Modes item summarizes every connected display, including Pinned Displays, and shows Mixed when those displays use different modes.

Settings Backup

Export or import portable preferences, shortcuts, rules, AI recipes, Snap Wheel built-in layout, and custom TabStack layouts. Display preferences and Saved Workspace shortcuts are included. Credentials, Stages, Saved Workspaces, and Custom Actions remain local. Reset All Settings clears rules and custom layouts and restores Compact appearance while keeping those local items and windows. Restart BetterStage is available from the menu-bar menu. See the Settings Backup guide.

After restart, sleep or wake, or a display change, BetterStage waits for apps and screens to settle, then safely repairs windows it can match. The recovery snapshot stays on this Mac and is never uploaded. Changes to this setting apply after restarting BetterStage.

Show recovery progress, warnings, actions, and Undo prompts. Turn this off to keep wake recovery and Workspace Continuity working silently. The change applies immediately and does not disable recovery or reconciliation. The display-return choice remains available.

Offline Display Shelf and its keep-aside setting are deprecated. Automatic workspace recovery makes windows available on connected displays and joins them to TabStack panes. On reconnection, the display's windows and layout return automatically; if BetterStage needs confirmation, a nonblocking prompt offers Restore Workspace or Keep Current Layout.

Manage, preview, rename, delete, or load named Workspaces, and use Save Current Workspace to capture one Stage or every Stage as a reusable setup. Automatic workspace recovery remains available on the free tier.

Choose from 25 provider presets — OpenAI, Claude, Gemini, OpenRouter, Groq, Mistral, DeepSeek, xAI, Qwen, Moonshot, Azure, and more, including local servers like Ollama and LM Studio. Each preset pre-fills its base URL and default model, fetches a live model list, offers a region picker where it matters, and remembers its own API key.

Prefer not to manage a key? BetterStage AI is a managed option (optional subscription) that runs AI Staging with no API key or provider setup — an alternative to the bring-your-own-key fields above.

Sends a real chat message to your configured model so you know the endpoint, key, and model all actually work before you depend on them.

Adjust how conservative or creative the model should be when it groups your windows. Lower values keep suggestions more stable.

Save different Recipes for different workflows, such as keeping chat apps on a side monitor, pairing project docs with your editor, or building a writing-focused setup. You can create, switch, duplicate, rename, delete, and mark a default Recipe. Edit the selected Recipe with the same @-mention chips as the chat panel, preview the exact prompt sent to the model, and run an arrangement straight from the panel.

Pick which mode a newly created stage starts in on each monitor: Enhanced Native, TabStack, or Bento Box (Legacy). Each monitor in each stage can still be changed afterwards from the Snap Wheel or the BetterStage menu bar.

Choose a preset independently of the default Window Mode. Use default layout automatically is off by default; turn it on to apply your chosen layout when entering TabStack. Existing choices are preserved when switching modes. Manage presets from the layout editor in the same pane — see Layout Presets.

New Window Placement

Choose Automatic, Active Pane, Adjacent Pane, or Own Pane for new TabStack windows. Adjacent Pane can prefer left, right, above, or below.

Split, Swap, and window rules

In Window Modes > Modes & Behavior, adjust Split drop zone size from 0–40% with a live preview; 0% disables Split. Enable Swap drop zone controls the regular Swap target; hold Option while dragging to swap even when it is disabled. Remembered Window Behaviors lets you edit, pause, or delete rules created from a window's Snap Wheel.

Layout Style

Compact (the default) uses 0 px pane/tab padding, 90% pane opacity, a transparent tab bar, 4 px screen padding, and 4 px gaps. Comfortable uses 4 px pane/tab padding, 90% pane opacity, an opaque tab bar, 8 px screen padding, and 6 px pane gaps. Manual edits select Custom.

Shared controls for every TabStack divider drag. Toggle ghost-frame previews or set the visible drag handle from 4 to 24 px. Its grab area stays three times wider than the visible divider for easier resizing. Direct divider drags resize only adjacent panes; independent rows and columns keep their own divider positions.

Pixel gap at internal TabStack pane seams. It does not add an outer-screen inset; screen padding controls the outer edges.

Padding between a TabStack pane's glass container and the app window inside it (0 – 32 px).

Opacity for the TabStack pane glass. App windows and tab labels stay fully readable.

Left and right inset around each TabStack tab bar (0 – 24 px). Raise it for a roomier bar; lower it for a tighter, denser look.

Opacity for the TabStack tab bar background. This adjusts the bar chrome without fading tab titles, buttons, or app windows.

Choose the tab bar edge for all TabStack panes. Left and Right turn the bar into a vertical rail of stacked tabs; Top and Bottom keep the classic horizontal strip. Existing profiles stay on Top.

Icons only shows each tab as a compact app-icon button. Hover a tab to see its full title and app name in a popover beside a vertical rail, toward the pane interior when space allows. The icon stays visible on hover: click it to select the window, drag it to move the tab, or right-click for Close.

Width of the vertical rail when the bar is on the left or right and titles are shown (140 – 320 pt). Row height comes from Tab height; in Icons only mode the rail thickness is controlled by Icon rail width(default 40 pt, 32 – 48 pt). Rows retain their size; scroll the rail when more tabs are available.

Keep windows full-pane and show tabs only when you move the pointer to that edge of an owned window. A small edge handle past the title-bar controls shows which panes have a tab bar. Native window-resize corners stay free of the hover band and of the revealed overlay. Divider resizing retains priority, and the rest of the window does not trigger reveal. The revealed bar has a solid background, regardless of Tab Bar Background opacity, and slides in from the chosen edge. The bar stays open during a tab drag, menu, or app launcher, then collapses back to the mark after you move away. Turning Auto-hide off immediately restores the full reserved bar and your saved transparency. Hide tab bar in single-window panes also removes auto-hidden tabs until a second window joins.

Choose how TabStack tabs fill the bar. Compact keeps tabs equal-width; Expanded stretches the last tab to use extra space. This applies to horizontal bars with titles. Vertical rails retain their row height and scroll when tabs do not fit; icon-only tabs stay compact.

Choose how the selected TabStack tab looks. Default keeps BetterStage's neutral glass; System Accent tints the selected tab with your macOS accent color. Find it in Settings > Window Modes.

Adjust tab height and, on vertical titled rails, tab bar width together. Also choose active and inactive text colors, and show or hide the empty-pane close button. Automatic text colors adapt for readable contrast. Reset to Defaults in Tab Appearance restores that section independently.

Configure one or more triggers to activate the snap wheel. All active triggers work simultaneously. Click Add Trigger to choose from presets or record a custom combo. Each trigger can be set to hold or toggle mode independently.

Default triggers: middle-click anywhere and a four-finger trackpad tap (both toggle). Presets include Ctrl+Opt hold, middle-click hold, left-click drag on title bar, Opt+drag near title bar, and 4- or 5-finger trackpad taps and clicks.

Defaults are 8 slots on the inner ring, 8 on the outer ring, and 13 in the More Actions submenu, including Raise Floats and Window Behavior. The default Workspace submenu contains AI Staging, Load Workspace, and Save Workspace. Rings support up to 12 slots; submenus support up to 16. Choose between the Glass and Classic styles, and tint the inner ring slices and outer disc independently. Pick custom SF Symbol icons for any slot. See Snap Wheel customization.

Shows every routing rule in evaluation order. Drag to reorder the list; the first enabled match wins. Each rule has an enable/disable toggle to temporarily pause it without deleting. If the target stage is later deleted, the rule shows a “Stage not found” warning.

Match an application, a window title, or require both. Apps excluded from staging in App Exceptions take priority over routing.

Pick any stage 1–9, even if the stage doesn’t exist yet. Stages that don’t exist are labelled “will be created” and are created when a new window matches the rule.

Send routed windows to a specific display. Leave it on “Any staged display” and the window stays on the display where it opened. Choose a Pinned Display to send new windows to its independent workspace; the rule does not switch or create a regular Stage.

Replaces the macOS app switcher. Turn off to get the native ⌘Tab back.

Grid or List + Preview.

How strongly the glass is tinted toward light or dark to keep text readable.

Live thumbnails of each window; needs Screen Recording. Without previews, the switcher shows app icons.

Minimized windows are restored when you pick them.

List only windows on the display under the pointer.

Exclude from Staging

Apps whose windows are always visible, regardless of which stage is active. Useful for note-taking, chat, or password managers you want everywhere.

Float in Window Modes

Apps remain owned by their Stage but do not participate in TabStack or legacy Bento tiling. They float freely above the layout. Good for browser session-restore prompts, color pickers, and small utility windows. To control just one window instead, use the Snap Wheel's Window Behavior action and choose Keep Floating.

Float Secondary Windows

Apps whose secondary windows shouldn't be auto-tiled even when the monitor is in TabStack — for example, preference panels or sheet-style dialogs.

Finder Quick Look previews stay out of your layouts by default. Turn this on to include them in the layout whenever they open. Close and reopen existing previews after changing it.

Reserve space around the edges of each monitor before BetterStage places tiled windows. Useful if you want breathing room around the menu bar, dock, or the outer edges of your layout.

Use Simple for one padding value on all sides, or switch to Custom to set independent top, bottom, left, and right padding.

Set the space at internal pane seams. Increase it for visual separation or drop it to zero for edge-to-edge panes; it does not inset the outer display edges.

Give a display its own screen padding and gap between panes; other displays use the shared settings. Identify Displays labels every connected screen so you know which one you are editing.

Max tiled windows per display (default and maximum 12) sets how many windows Retile arranges in Enhanced Native. Move overflow to the next Stage (default on) sends the rest to another Stage; when off, extra windows stay free on this Stage.