Vorssaint Window Switcher Permissions: What macOS Access You Need and Why

Vorssaint's window switcher requires macOS Accessibility permission for core hotkey and window management functionality, while Screen Recording permission is optional but required for live thumbnails and window title detection.

The vorssaint/vorssaint-utils repository hosts a powerful window switcher for macOS that balances deep system integration with user privacy. According to the source code, the implementation uses a two-tier permission model that allows the app to function even when users decline certain access rights.

Required vs. Optional Permissions for the Vorssaint Window Switcher

The switcher distinguishes between Accessibility (essential for basic operation) and Screen Recording (enhances visual features). Both permissions are technically optional—if denied, the switcher falls back to displaying app icons without live previews.

Accessibility Permission (Required for Core Features)

macOS protects keyboard input monitoring and window enumeration behind the Accessibility permission. In docs/PERMISSIONS.md (lines 28-30), the documentation specifies that this permission enables the switcher to:

• Capture global hotkeys
• Read the list of open windows from other applications
• Drive scrolling actions, Dock preview integration, middle-click handling, and radial-menu key actions

The AppSwitcher.swift file validates this access using ApplicationServices framework calls:

import ApplicationServices

/// Returns true if the app is trusted for Accessibility.
func hasAccessibilityPermission() -> Bool {
    return AXIsProcessTrusted()
}

Without this permission, the switcher cannot detect which windows are open or respond to keyboard shortcuts.

Screen Recording Permission (Optional for Enhanced UI)

macOS classifies reading other windows' titles and capturing live thumbnails as Screen Recording. As noted in docs/PERMISSIONS.md (line 47), this permission supports:

• Live window thumbnails in the switcher interface
• Dock Preview functionality
• Screenshot capabilities
• Copy-text-from-screen features

Check for this authorization using AVFoundation:

import AVFoundation

/// Returns true if the app has permission to capture the screen.
func hasScreenRecordingPermission() -> Bool {
    let status = AVCaptureDevice.authorizationStatus(for: .video)
    return status == .authorized
}

If the user denies Screen Recording, Sources/Vorssaint/Services/Switcher/AppSwitcher.swift automatically degrades to showing static app icons rather than live previews.

Implementation Details in the Source Code

The permission logic resides in two primary locations within the repository:

1. Sources/Vorssaint/Services/Switcher/AppSwitcher.swift – Contains the runtime checks for AXIsProcessTrusted() and ScreenCapture usage, determining which UI mode to present based on current authorization status.

2. Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift – Houses the WindowServer identifiers and low-level support code that the switcher requires to interact with the macOS windowing system.

3. docs/PERMISSIONS.md – Serves as the canonical documentation mapping each feature to its required entitlement.

Graceful Degradation When Permissions Are Denied

According to the source analysis, the switcher implements a robust fallback strategy:

• Accessibility denied: The app cannot function as a switcher (no window detection or hotkey capture).
• Screen Recording denied: The switcher continues operating but displays generic application icons instead of live thumbnails, and disables Dock Preview, screenshots, and text extraction features.

This design ensures users retain basic window switching capabilities even when privacy concerns prevent full system access.

Programmatically Requesting System Access

When permissions are missing, the codebase includes utilities to direct users to System Settings. Use AppKit to open the specific preference pane:

import AppKit

func openAccessibilitySettings() {
    let url = URL(string: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility")!
    NSWorkspace.shared.open(url)
}

For Screen Recording settings, developers typically construct a similar URL pointing to the Screen Recording privacy section.

Summary

• Accessibility permission is essential for the Vorssaint window switcher to capture hotkeys and enumerate open windows, as implemented in AppSwitcher.swift using AXIsProcessTrusted().
• Screen Recording permission is optional but required for live thumbnails, window titles, and screenshot functionality; without it, the switcher falls back to basic app icons.
• Both permissions are checked at runtime, with the code gracefully degrading features when access is denied rather than failing entirely.
• Permission documentation is centralized in docs/PERMISSIONS.md, while implementation details reside in the Sources/Vorssaint/Services/Switcher/ directory.

Frequently Asked Questions

Does the Vorssaint window switcher work without Accessibility permissions?

No. According to the source code in Sources/Vorssaint/Services/Switcher/AppSwitcher.swift, the switcher requires Accessibility access to detect open windows and register global hotkeys. Without this permission granted in System Settings, the core switching functionality cannot operate because macOS blocks window enumeration and keyboard event monitoring.

Why does a window switcher need Screen Recording permission?

macOS classifies reading other applications' window titles and capturing live thumbnails as screen recording activities. The AppSwitcher.swift implementation uses this permission to display live window previews and enable features like Dock Preview and copy-text-from-screen. If denied, the switcher continues functioning but shows only static application icons rather than live window thumbnails.

How can I check if Vorssaint has the required permissions programmatically?

Use the ApplicationServices framework to verify Accessibility rights via AXIsProcessTrusted(), and AVFoundation's AVCaptureDevice.authorizationStatus(for: .video) to check Screen Recording status. The repository provides these exact implementations in its permission utilities, returning Boolean values indicating whether each specific entitlement is granted.

What happens if I deny Screen Recording but grant Accessibility?

The switcher enters a degraded mode where it can still switch between applications using Accessibility APIs, but displays generic app icons instead of live window thumbnails. Features requiring pixel access—such as screenshots, copy-text-from-screen, and Dock Preview—are automatically disabled in AppSwitcher.swift when hasScreenRecordingPermission() returns false.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}