Docs / Core Concepts
AI Staging
Describe the workspace you want in the AI Staging chat panel — @-mention specific apps, windows, stages, or monitors — and AI analyzes your open windows (titles, URLs, file paths), then proposes a stage plan you can review, refine, apply, or undo with one step (Cmd-Z in the panel). Requires a Pro license 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.
- Scan — BetterStage reads window titles, document paths, URLs, and app names for every open window.
- Analyze — The data is sent to your LLM provider. The chat panel streams progress and keeps the proposed actions attached to the assistant response.
- Review and apply — New stages are created and windows are assigned to the right monitor on each stage, using the default Window Mode you have set in Settings (macOS Native by default). You can refine the plan before applying it, and undo the applied envelope afterward.
Triggering AI Staging
There are four ways to run AI Staging:
- Keyboard shortcut — Press the AI Staging shortcut if you have one assigned in Settings > Shortcuts.
- Menu bar — Click the BetterStage menu bar icon and select AI Staging…
- Snap Wheel — Open the Snap Wheel's More Actions 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. BetterStage ships with 25 provider presets: OpenAI, Claude (Anthropic), Google Gemini, OpenRouter, Groq, Together AI, Mistral, xAI (Grok), DeepSeek, Moonshot (Kimi), Zhipu (GLM), Alibaba Qwen, MiniMax, Tencent Hunyuan, ByteDance Doubao, NVIDIA NIM, Hugging Face, Azure OpenAI, and more — including local servers like Ollama and LM Studio.
- Live model lists — pick a preset and BetterStage fetches the models your key can actually use.
- Region picker — providers with regional endpoints (Qwen, Moonshot, Zhipu, MiniMax, SiliconFlow) let you switch between domestic and international base URLs.
- Per-provider API keys — each provider remembers its own key, so switching presets never loses a key.
- Custom endpoint — the Custom (OpenAI-compatible) preset accepts any base URL and model name, e.g. a proxy or self-hosted server.
| Provider | Default Model | Auth |
|---|---|---|
| OpenAI | gpt-4.1-mini | API key (Bearer token) |
| Claude (Anthropic) | claude-sonnet-4-6 | API key (x-api-key header) |
| Ollama (local) | your installed model | None (localhost) |
| Custom (OpenAI-compatible) | any | API key (Bearer token) |
The other 21 presets follow the same OpenAI-compatible pattern with their base URL and default model pre-filled.
Test Connection
Settings > AI Staging includes a Test Connection button that 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. Setup problems are caught before the request with a clear message and an Open Settings button instead of a raw provider error.
Window Rules
You can save standing Window Rules for how your workspace should be arranged. The chat panel leads with your saved rules: edit them with the same @-mention chips as the live chat (monitors, stages, windows, apps, and Window Modes), preview the exact prompt sent to the model, and run an arrangement straight from the panel.
Example rules:
- “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 keystrokes are sent. Window titles, file paths, and URLs can still contain sensitive project or document names, so choose a provider you trust.
Requirements
- Pro license — AI Staging is a Pro feature.
- API key — You must provide your own API key for one of the 25 supported providers (or any OpenAI-compatible endpoint).
- Internet connection — Required for cloud providers. Local servers (Ollama, LM Studio) work offline.