BETTERSTAGE

Docs / Core Concepts

AI Staging

One click and AI analyzes every open window — titles, URLs, file paths — and groups them into project-focused stages. Requires a Pro subscription and your own API key.

How It Works

AI Staging scans every open window on every monitor, collects metadata (app name, window title, document path, URL), and sends it to your chosen LLM provider. The model returns a plan that creates named stages and assigns each window to the right stage and monitor.

  1. Scan — BetterStage reads window titles, document paths, URLs, and app names for every open window.
  2. Analyze — The data is sent to your LLM provider. A live overlay shows progress as the model streams its analysis.
  3. Apply — New stages are created, windows are assigned, and auto-tiling is enabled on each stage. The overlay confirms how many stages and windows were organized.

Triggering AI Staging

There are three ways to run AI Staging:

  • Menu bar — Click the BetterStage menu bar icon and select AI Staging…
  • Snap Wheel — Open the Snap Wheel's Extras submenu and click AI Stage.
  • Settings — Open Settings > AI Staging to configure your provider, then run from there.

Provider Setup

AI Staging uses your own API key — no data passes through BetterStage servers. Configure your provider in Settings > AI Staging.

ProviderDefault ModelAuth
OpenAI (Official)gpt-4.1-miniAPI key (Bearer token)
OpenAI-Compatiblegpt-4.1-miniAPI key (Bearer token)
Claudeclaude-sonnet-4-6API key (x-api-key header)

You can change the base URL and model name to point at any compatible endpoint (e.g. a local model, Azure OpenAI, or a proxy).

Custom Instructions

You can optionally provide custom instructions that override the default grouping behavior. These are sent to the LLM as highest priority rules.

Example instructions:

  • “Put chat apps and music on the small side monitor. Keep browser tabs with project docs next to the editor.”
  • “Always create a Comms stage for Slack, Discord, and email.”
  • “Group by client name when possible.”

What Data Is Sent

AI Staging sends a workspace snapshot directly to your chosen provider. BetterStage servers never see this data. The snapshot includes:

  • Window metadata — app name, window title, document file path, content URL (host + path)
  • Monitor layout — display names, arrangement order, frame bounds, primary/secondary status
  • System constraints — max stage count, max windows per stage

No file contents, screenshots, or personal data are sent — only window titles and paths.

Requirements

  • Pro subscription — AI Staging is a Pro feature.
  • API key — You must provide your own OpenAI or Anthropic API key (or a compatible endpoint).
  • Internet connection — Required to reach the LLM provider.