OSXR

Experimental — tested exclusively on the XREAL One Pro under macOS Tahoe 26.3. Stability, movement tracking accuracy, and edge-case handling are still being actively improved. Use at your own risk.

OSXR is a native macOS XR workspace for XREAL One Pro glasses.

Motivation

XR glasses like the XREAL One Pro expose a high-quality spatial display, but give little control over how that virtual space is organised. OSXR was built to reclaim that control: instead of a single floating window dictated by the glasses' firmware, it lets you define your own virtual desktop layout — currently 2 screens side by side or a 3-screen arc — positioned, curved, and sized exactly as you want. The goal is to make the virtual space genuinely useful as a daily macOS workspace.

It creates real macOS virtual displays, captures their live desktop content with ScreenCaptureKit, and renders those desktops as spatial monitors on the XREAL display. The app runs as a menu-bar accessory instead of a normal Dock app.

What This Package Enables

• True macOS virtual displays on top of the private CGVirtualDisplay API
• A head-tracked XR workspace rendered with Metal on the XREAL display
• 2-screens and 3-screens workspace layouts
• Per-layout tuning for:
  • screen size
  • screen distance
  • angle between screens
  • panel curvature
• Startup drift calibration for the XREAL IMU
• Manual recenter and recalibration shortcuts
• Automatic relocation of ordinary app windows back onto the visible XR monitors when they open elsewhere

How It Works

At a high level, OSXR does four things:

1. Creates macOS virtual displays.
2. Captures those displays with ScreenCaptureKit.
3. Reads head-tracking data from the XREAL One Pro IMU link.
4. Re-renders the captured desktops as curved or flat panels in a 3D workspace on the glasses.

Important caveat:

• This is not a true macOS display driver or compositor extension.
• It is a native macOS app that creates real virtual monitors and then re-renders them in XR.
• Because of that, some macOS behaviors such as Mission Control / Spaces gestures are still limited by the underlying windowing model.

Requirements

• macOS 13 or newer (tested on macOS Tahoe 26.3)
• Xcode / Command Line Tools with Swift 6 toolchain support
• XREAL One Pro connected to the Mac
• Screen Recording permission
• Accessibility permission

Installation

There is no separate installer right now. Build and run the package directly:

git clone <this-repo>
cd xr-os
swift build

If your local Xcode license has not been accepted yet, macOS may block the build until you run:

sudo xcodebuild -license

Launching

Run the app from the project root:

swift run

When it launches successfully:

• it creates a menu-bar item named XR
• it opens the XR workspace on the XREAL display
• it creates the backing virtual displays used by the workspace

The app uses the accessory activation policy, so it behaves like a background workspace utility rather than a regular foreground app.

First-Launch Permissions

The first launch needs macOS permissions before the XR workspace can fully work.

Screen Recording

Why it is needed:

• OSXR uses ScreenCaptureKit to capture the content of the virtual displays it creates.
• Without Screen Recording, the XR monitors exist, but they cannot show the real desktop content.

What you should expect:

• macOS will ask for Screen Recording permission.
• If you deny it, the app cannot show the real content of the virtual monitors until permission is granted.

Accessibility

Why it is needed:

• OSXR uses Accessibility APIs to move and rescue ordinary app windows back onto the visible XR monitors.
• Without Accessibility, apps and windows may open somewhere outside the visible XR workspace and stay there.

What you should expect:

• macOS will ask for Accessibility permission.
• If you deny it, the XR displays can still render, but automatic window placement and rescue will be limited.

If You Previously Denied Permission

If macOS no longer shows the prompt, re-enable access manually in:

• System Settings > Privacy & Security > Screen Recording
• System Settings > Privacy & Security > Accessibility

Then relaunch OSXR.

Controls

Menu Bar

The XR menu-bar item exposes the current workspace controls:

• Layout
  • 2 screens
  • 3 screens
• Screen Size
• Screen Distance
• Angle
• Curve
• Center
• Calibrate
• Quit

Keyboard Shortcuts

• Shift + Option + Command + Space
  • recenter the workspace
• Shift + Option + Command + R
  • recalibrate drift for 5 seconds
• Shift + Option + Command + Q
  • quit OSXR

Recommended Usage Notes

• Use the XREAL mode that keeps the display in front of you rather than anchoring the glasses' own UI in world space, since OSXR already provides its own spatial layout.
• If windows appear outside the visible XR monitors, give the app a moment: the window rescue pass runs continuously and should pull ordinary windows back into the visible XR workspace.
• If head tracking looks wrong or drifts, use Calibrate or the recalibration shortcut.

Architecture

• Package.swift
  • SwiftPM package definition
• Sources/XRVirtualDisplayBridge
  • Objective-C bridge over the private CGVirtualDisplay API
• Sources/XROSApp/AppController.swift
  • app lifecycle, permissions, menu bar, workspace boot, layout application
• Sources/XROSApp/Models.swift
  • monitor geometry, layout math, presets
• Sources/XROSApp/ScreenCaptureCoordinator.swift
  • ScreenCaptureKit display capture
• Sources/XROSApp/WorkspaceRenderer.swift
  • Metal compositor for the XR monitor surfaces
• Sources/XROSApp/XREALIMUClient.swift
  • direct IMU client for XREAL One Pro
• Sources/XROSApp/HeadPoseEstimator.swift
  • calibration and pose estimation
• Sources/XROSApp/WindowPlacementCoordinator.swift
  • window placement and rescue onto visible XR monitors

Calibration

When OSXR launches it runs a brief drift calibration for the XREAL IMU. During those first seconds:

• Keep your head completely still — any movement will be baked into the calibration baseline and cause the virtual workspace to drift.
• The calibration completes automatically; the workspace then appears in front of you.

You can redo calibration at any time by clicking Calibrate in the XR systray menu (or pressing Shift + Option + Command + R). The same menu is where you adjust all workspace options — screen size, distance, angle between panels, curvature, and layout — so you never need to relaunch the app to tune the experience.

Known Limitations

• The package relies on a private macOS virtual-display API (CGVirtualDisplay).
• Mission Control / Spaces behavior is not fully equivalent to a true XR-native display driver.
• Some apps may still use unusual window behaviors that require special-case rescue logic.
• IMU tracking depends on the XREAL One Pro exposing its expected network link to the Mac.
• Movement tracking is still being optimised — rapid head movements may produce visible drift until a recalibration is performed.
• Tested only on the XREAL One Pro under macOS Tahoe 26.3; other XREAL models and macOS versions are untested and may not work.

Quick Start

cd xr-os
swift run

If it is your first launch:

1. grant Screen Recording
2. grant Accessibility
3. relaunch if macOS requires it

After that, use the XR menu-bar item to tune the workspace.

---

License

MIT — see LICENSE.
Copyright © 2026 Laurent-Philippe Albou.

Acknowledgments

OSXR relies entirely on Apple system frameworks (Metal, ScreenCaptureKit, CoreGraphics, AppKit, Network, and others). See ACKNOWLEDGMENTS.md for the full list.