Immersive Mode

What Immersive Mode Does

Immersive mode replaces the passthrough view of your room with a fully rendered black environment. Your terminal windows stay where they are, but the world behind them goes dark. It is the visionOS equivalent of dimming the room lights, putting on noise-cancelling headphones, and closing the blinds — without standing up.

vmux ships two flavors of immersive mode. You can switch between them at any time:

• Full Blackout — every direction is black. You only see the windows you have open.
• Desk Cutout — most of your space is black, but a configurable rectangle in front of you remains transparent so you can still see your desk, keyboard, mug, or anything else within the cutout. The black region wraps the rest of the room with a vertical "curtain" that fades to a doorway above the desk.

Both flavors can show a faint yellow floor grid for spatial reference. The grid fades with distance so it does not draw your eye away from the terminal.

When to Use It

Immersive mode is built for sustained terminal work, not for quick lookups. Reach for it when you want to:

• Focus on a long-running task — code review, debugging a flaky deploy, or anything that benefits from removing visual chatter from your room.
• Read late at night — the all-black backdrop drops the average luminance of your view, which is much easier on your eyes in a dark room than passthrough plus bright windows.
• Treat the terminal like a theater screen — bring up a single full-resolution window, dim everything else, and let it dominate your view.
• Isolate from a busy room — co-working spaces, planes, hotel rooms — anywhere the passthrough is a distraction.

Use Desk Cutout when you still need to type on a physical keyboard or reach for a coffee cup. The cutout is sized in real-world meters, so once you tune it to your desk it stays tuned.

Enabling Immersive Mode

There are three ways to enter or exit immersive mode. They all do the same thing — pick whichever fits the moment.

Command Palette

Open the Command Palette (Cmd+Shift+P) and type "blackout". Three commands are available:

The active flavor (Full Blackout vs Desk Cutout) is determined by your current settings. Toggle the Desk Cutout option to switch.

Voice

If voice control is active, say:

• "toggle blackout" or "blackout" — toggle on or off
• "enter blackout" — open it
• "exit blackout" — dismiss it

See Voice Commands for setup and supported phrases.

Keybind

You can assign a keyboard shortcut to any of the blackout commands from the keybind editor in Settings. Most users bind Toggle Blackout to a chord that is easy to hit eyes-closed, like Cmd+Shift+B.

Exiting Immersive Mode

There are several ways out:

• Run Exit Blackout from the command palette, or use your assigned keybind.
• Press the Digital Crown on the headset to dismiss the immersive space — this is the standard visionOS gesture and works the same as in any other immersive app.
• Toggle the command again (Toggle Blackout closes if it is already open).
• Quit vmux. Immersive spaces are torn down with the app.

If the system dismisses the immersive space for you (for example because another app opened its own immersive scene), vmux notices and updates its internal state so the next toggle reopens cleanly.

Configuring Desk Cutout

The Desk Cutout settings let you describe the rectangle of real space you want to keep visible. Open them from the Desk Cutout panel in the Workspace Panel or from the immersive section of Settings. All measurements are in meters and apply live as you adjust them.

Use the Reset button at the bottom of the panel to restore default measurements (1.25 m wide, 0.75 m deep, 0.82 m tall, centered, 0.9 m forward). The Open Blackout button enters immersive mode in whichever flavor your current settings select.

If you cannot see your desk after enabling Desk Cutout, the cutout is probably positioned wrong relative to where you set up your space. Recenter the visionOS view (Digital Crown long-press) and try again, or nudge Forward and Left/Right until the cutout aligns.

How It Interacts With Passthrough

Immersive mode is rendered on top of passthrough. visionOS still tracks the real world for hand input, eye gaze, and safety, but the renderer paints opaque black geometry around you.

• People nearby — visionOS Persona awareness still triggers. If someone walks up to you, the system will flash a passthrough cutout of them through the black backdrop. You will see them through the void.
• Hand input — your hands and the cursor halo continue to render normally. Eye gaze still steers focus through the black space.
• Notifications — visionOS notifications still appear above your environment.
• Other windows — windows from other apps stay visible. Immersive mode dims your environment, not your apps.

Known Limits

• Single immersive space at a time. visionOS only allows one immersive space per user. If another app (Disney+, Encounter Dinosaurs, etc.) takes over, vmux's blackout closes automatically. Reopen it after the other app is done.
• No partial-room masking yet. Desk Cutout is a single rectangle. If your desk is L-shaped or wraps a corner, only one rectangular slice will be transparent.
• Floor grid is purely visual. It is not anchored to detected floor planes — it sits at a fixed height below your seated viewpoint.
• Battery and thermals. Rendering an immersive scene uses more GPU than plain windows. On hot days or low battery, you may notice the headset warm up faster.

Related

• Settings — full settings reference, including the Blackout panel
• Command Palette — how to find any command
• Voice Commands — voice phrases for blackout