What Utilities Does Vorssaint-Utils Provide? Complete macOS Menu Bar Toolkit

Vorssaint-Utils is a modular macOS menu bar application that bundles over a dozen independent system utilities—including per-app audio control, window snapping, clipboard history, and hardware monitoring—into a single, permission-first toolkit.

Vorssaint-Utils (vorssaint/vorssaint-utils) consolidates functionality typically scattered across separate paid tools into one cohesive Swift codebase. Each utility lives as an independent module under Sources/Vorssaint, exposing both a SwiftUI interface and programmatic APIs for scripting and automation.

Audio Control Utilities

The audio suite in Vorssaint-Utils provides system-level control over macOS audio routing and per-application volumes. At the core is AppVolumeMixer, implemented in Sources/Vorssaint/Services/Audio/AppVolumeMixer.swift, which manages CoreAudio taps and exposes @Published properties for reactive UI updates.

Key capabilities include:

• Per-app volume mixer – Control individual application volumes independently of the system master
• Per-app output routing – Direct specific apps to different audio devices (headphones, speakers, interfaces)
• Microphone pinning – Lock microphone input to prevent apps from switching devices
• Music app blocker – Prevent the Music app from auto-launching
• Headphone safety – Automatically lower volume when disconnecting headphones

The AppVolumeMixer class provides methods like setVolume(_:for:) to adjust levels and setUniversalOutputDeviceUID(_:) for device switching, persisting all changes via DefaultsKey storage.

Window and Dock Management

Window management utilities are handled primarily in Sources/Vorssaint/UI/Window/WindowGestureControls.swift. These features enhance macOS window manipulation beyond the native capabilities:

• Enhanced Command-Tab switcher – Live thumbnails with window grouping and multi-window support
• Window snapping – Magnetic snapping to halves, thirds, and corners with gesture controls
• Dock enhancements – Preview thumbnails on dock hover, quit-on-close protection, and configurable dock-click actions
• Layout preservation – Remember and restore window positions across displays

System Monitoring Tools

Real-time hardware monitoring is driven by tests in Sources/Vorssaint/Services/VMStatisticsCompat and UI panels that consume system metrics:

• Real-time graphs – CPU, GPU, memory, and temperature visualization
• Battery health – Detailed cycle count and capacity reporting
• Fan control – Beta support for manual fan curves and thermal management
• Network monitoring – Live throughput rates and integrated speed testing
• System alerts – Notifications for high CPU load, memory pressure, or low disk space

Keyboard and Mouse Automation

Input device customization is also coordinated through WindowGestureControls.swift and related services:

• Text snippet expansion – Trigger custom text replacements via shortcuts
• Super key remapping – Map Caps Lock to function as Option, Control, or Command via SuperKeySettings
• Smooth scrolling – Custom scroll acceleration curves and direction inversion
• Focus follows mouse – Optional X11-style focus behavior
• Key debouncing – Prevent accidental double-presses on mechanical switches
• Side-button shortcuts – Configure mouse buttons beyond native macOS support

Clipboard and File Utilities

The clipboard system (implicit in Sources/Vorssaint/UI/Clipboard) and Shelf feature provide data management tools:

• Clipboard history – Persistent history with pinning, auto-clear timers, and search
• Paste as plain text – Strip formatting from copied rich text
• URL cleaning – Automatically remove tracking parameters from copied URLs via ClipboardCleaner.shared
• Shelf – A quick drop-zone for files and text, accessible from the menu bar
• Finder enhancements – Native cut/paste shortcuts and disk image one-click mounting

Productivity and Everyday Tools

Under Sources/Vorssaint/UI/, Vorssaint-Utils includes several standalone productivity modules:

• Command Bar (CommandBar.swift) – Quick launcher for actions, snippets, and file search
• Radial Menu (RadialMenu.swift) – Contextual pie-menu for frequently used actions
• Screenshot and Screen Recording Editor – Built-in annotation tools, GIF export, and QR code overlay generation
• Scratchpad – Persistent quick notes accessible from the menu bar
• Homebrew Manager – GUI interface for Homebrew package management
• App Cleaner – Detect and remove application leftovers and caches
• Cleaning Mode – Lock keyboard input while cleaning the device

Energy and Display Management

Power user features for display and sleep control:

• Keep-Awake Timer (Sources/Vorssaint/UI/KeepAwake/KeepAwakeView.swift) – Prevent sleep with options for lid-closed operation, external-display awareness, and lock-screen exceptions
• Per-display brightness – Independent control for multiple monitors including HDR brightness boosting
• Bluetooth sleep management – Automatically disable Bluetooth during sleep to save power, managed via settings related to DiskExclusionsList.swift

Modular Architecture and Installation

Vorssaint-Utils employs a strictly modular architecture where each utility is an optional component:

1. Feature Modules – Each utility resides in its own folder (e.g., Sources/Vorssaint/Services/Audio/ for audio features) exposing public Swift APIs
2. Central Services – Low-level system access (CoreAudio, IOKit) is abstracted into reusable service classes
3. Feature Hub – Sources/Vorssaint/UI/Settings/FeatureHubSettings.swift manages installation, uninstallation, and per-feature permission requests
4. Uninstaller – Tools/uninstall.sh provides complete removal of the app, preferences, and revoked permissions

Permissions are handled granularly according to docs/PERMISSIONS.md, requesting only Accessibility, Screen Recording, or System Audio Recording when specific features are enabled.

Programmatic Usage Examples

You can interact with Vorssaint-Utils services directly in Swift scripts or other macOS applications.

Adjust Per-App Volume

let mixer = AppVolumeMixer.shared

if let safari = mixer.apps.first(where: { $0.persistenceID == "com.apple.Safari" }) {
    mixer.setVolume(0.5, for: safari)
}

Implementation resides in Sources/Vorssaint/Services/Audio/AppVolumeMixer.swift, where setVolume updates CoreAudio taps and persists values.

Switch Audio Output Device

let deviceUID = "AppleUSBAudioEngine-1"
let success = AppVolumeMixer.shared.setUniversalOutputDeviceUID(deviceUID)

Configure Super Key (Caps Lock Remapping)

let superKey = SuperKeySettings.shared
superKey.enabled = true
superKey.modifier = .option

Handled within the keyboard utilities system.

Clean Clipboard URLs

let url = URL(string: "https://example.com?utm_source=mail")!
ClipboardCleaner.shared.add(url)

Summary

• Vorssaint-Utils provides per-app audio control, window snapping, system monitoring, and clipboard management in a single menu bar app.
• Utilities are built as optional Swift modules installable via the Features hub in FeatureHubSettings.swift.
• The architecture exposes programmatic APIs for automation while maintaining privacy-first, local-only data storage.
• Source files like AppVolumeMixer.swift and WindowGestureControls.swift demonstrate direct integration with CoreAudio and macOS windowing APIs.
• Complete removal is handled by Tools/uninstall.sh with granular permission revocation.

Frequently Asked Questions

How does Vorssaint-Utils handle macOS permissions?

The app requests permissions granularly based on enabled features. According to docs/PERMISSIONS.md, it only asks for Accessibility, Screen Recording, or System Audio Recording when you activate specific utilities. The FeatureHubSettings.swift module re-prompts users if a feature is toggled on without the necessary permissions.

Can I install only specific utilities without the full suite?

Yes. The Features Hub (Sources/Vorssaint/UI/Settings/FeatureHubSettings.swift) allows modular installation of individual utilities. Each feature lives in its own Swift module (e.g., Sources/Vorssaint/UI/KeepAwake for the sleep timer), and you can uninstall specific features later without affecting the rest of the application.

Is Vorssaint-Utils designed for privacy and local operation?

According to the repository source, Vorssaint-Utils maintains privacy-first defaults with no telemetry and local-first data storage. All settings persist via standard UserDefaults (DefaultsKey.*), and the app does not transmit usage data or require cloud connectivity.

How do I completely uninstall Vorssaint-Utils?

Run the Tools/uninstall.sh script included in the repository. This shell script removes the application bundle, deletes preference files, and triggers macOS permission revocation dialogs to ensure no system access remains after removal.

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