Settings Reference

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

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.

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.

Keeps hidden windows near their owning display when a bottom corner has enough clear room, which can make stage switching, Bento Box changes, and Tabbed Layout tab switching faster on multi-monitor setups. Turn it off to always use the global hide corner instead.

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, reconciliation, or the Offline Display Shelf.

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: macOS Native, Bento Box, or Tabbed Layout Mode. Each monitor in each stage can still be changed afterwards from the Snap Wheel or the BetterStage menu bar.

When a new stage is created with Tabbed Layout Mode as its default, this preset is loaded automatically. Manage presets from the layout editor in the same pane — see Layout Presets.

Shared controls for Bento Box and Tabbed Layout divider drags. 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.

Pixel gap between tiled windows in Bento Box and between panes in Tabbed Layout Mode. Set to 0 for edge-to-edge.

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

Opacity for the Tabbed Layout Mode pane glass. App windows and tab labels stay fully readable.

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

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

Choose how Tabbed Layout tabs fill the bar. Chrome keeps tabs compact and equal-width; Safari stretches the last tab to use extra space.

A Reset button on the Tabbed Layout sliders returns Tabbed Container Padding, Pane Opacity, Tab Bar Padding, Tab Bar Background, and Tab Width Style to their defaults in one click.

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 trigger: middle-click anywhere (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 9 in the More Actions submenu. Each ring or submenu can be resized to between 1 and 12 slots from the layout editor. Choose between Liquid 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.

Enable keyboard and edge-drag snap zones. When active, dragging a window to the edge of a screen or using keyboard shortcuts snaps it to predefined zones (halves, quarters, thirds, etc.).

Shows every app you’ve assigned to a stage, with the target stage number and any monitor preference. 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.

Choose any app on your Mac — use the file picker to browse your Applications folder, or search by name. Excluded apps (from the Exclude Apps pane) are filtered out since exclusion takes 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” — they’re created automatically when you save the rule or when the app next opens a window. Use it to plan your workspace ahead of time.

Pin the routed windows to a specific monitor. Leave it on “Any Monitor” and BetterStage places the window where your cursor is. Pinned displays (from the Displays pane) are filtered out of the picker.

After saving a rule, click “Move existing windows now” to apply it retroactively to every currently-open window from that app. Uses the same undoable move operation as AI Staging.

Exclude from Stages

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 that never participate in Bento Box or Tabbed Layout Mode. They float freely above the grid. Good for browser session-restore prompts, color pickers, and small utility windows. Can also be toggled from the Snap Wheel via Exclude App.

Popup Tiling

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

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 between tiled windows. Increase it for more visual separation or drop it to zero for edge-to-edge tiling.