What Are the Core Functionalities of Vorssaint-Utils?

Vorssaint-Utils consolidates audio control, system monitoring, window management, and productivity automation into a single macOS menu-bar application built on SwiftUI ObservableObjects, featuring both a graphical interface and command-line diagnostic utilities.

Vorssaint-Utils (vorssaint/vorssaint-utils) is a comprehensive macOS utility suite designed to replace multiple paid applications with one lightweight, always-available menu-bar icon. The project implements a modular architecture where each major feature is encapsulated as an ObservableObject service that exposes state to SwiftUI panels, while Sources/Vorssaint/main.swift provides a lightweight command-line entry point for diagnostics and uninstallation.

Architecture: ObservableObject Services and SwiftUI

The codebase is structured around reactive ObservableObject services that publish state changes to SwiftUI views. This pattern allows the menu-bar panels to display real-time data—such as CPU temperature or audio volume—without blocking the main thread. The entry point in Sources/Vorssaint/main.swift parses command-line arguments like --selftest, --sensors, and --uninstall to trigger diagnostics or removal routines before launching the NSApplication instance.

Audio and Media Management

Per-App Volume Mixer

The Per-App Volume Mixer exposes every macOS audio process as an individually controllable entity. As implemented in Sources/Vorssaint/Services/AppVolumeMixer.swift, the service detects applications with active audio connections and allows you to adjust their volume levels beyond 100%, route output to specific devices, or mute them independently. The UI implementation in Sources/Vorssaint/UI/MenuPanel/MixerSection.swift renders these controls in a scrollable list within the menu panel.

import Vorssaint

// Retrieve the shared mixer service
let mixer = AppVolumeMixer.shared

// List all apps currently playing audio
for app in mixer.apps where app.isPlaying {
    print("\(app.name) – volume: \(Int(app.volume * 100))%")
}

// Set the system output volume to 75 %
if let current = mixer.systemOutputVolume {
    mixer.setCurrentOutputVolume(0.75)
}

Media Tools

Sources/Vorssaint/Services/Media/MediaTools.swift provides local-only conversion utilities for video, audio, and images. These tools handle compression, GIF creation, and screen-capture editing without transmitting data to external services, ensuring privacy for sensitive media workflows.

System Monitoring and Diagnostics

Real-Time Hardware Monitoring

The System Monitor service defined in Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift samples hardware metrics on a background queue, adapting its cadence based on which panels or widgets are currently visible. It aggregates data from Sources/Vorssaint/Services/SystemMonitor/SMCClient.swift to read CPU and GPU temperatures, fan speeds via the System Management Controller, memory pressure, network traffic, disk I/O, and power metrics.

import Vorssaint

let snapshot = SystemMonitor.shared.snapshot

if let cpu = snapshot.cpuUsage {
    print("CPU usage: \(Int(cpu * 100))%")
}
if let gpu = snapshot.gpuUsage {
    print("GPU usage: \(Int(gpu * 100))%")
}
if let temp = snapshot.cpuTemperature {
    print("CPU temperature: \(temp) °C")
}

Command-Line Diagnostics

When launched with flags, the binary bypasses the GUI to execute maintenance routines:

• --selftest: Runs an internal diagnostics suite verifying service initialization
• --sensors: Dumps raw SMC sensor data including thermal readings and fan speeds
• --uninstall: Removes the app and its associated settings files

/Applications/Vorssaint.app/Contents/MacOS/Vorssaint --selftest
/Applications/Vorssaint.app/Contents/MacOS/Vorssaint --sensors
./Tools/uninstall.sh

Window Management and Navigation

App Switcher and Dock Previews

Sources/Vorssaint/Services/Switcher/AppSwitcher.swift implements an enhanced Command-Tab experience that displays live window thumbnails and supports grouping by application. When you hover over a Dock icon, Sources/Vorssaint/UI/MenuPanel/DockPreviewPanelView.swift renders live thumbnails of that application's windows; clicking a thumbnail activates the specific window, while dragging it initiates a move operation.

Window Layout and Snapping

Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift provides window manipulation capabilities including snapping to halves, thirds, or corners, moving windows between displays, and restoring previous placements. Sources/Vorssaint/Services/WindowLayout/WindowGestureSupport.swift adds edge-snapping with visual guides triggered by mouse gestures.

Productivity Utilities

Clipboard History

Sources/Vorssaint/Services/Clipboard/ClipboardHistory.swift maintains a local database of copied text, images, and files with configurable automatic expiration. The service supports pinning important items, full-text search, and quick-paste keyboard shortcuts without cloud synchronization.

Text Snippets

Configured via Sources/Vorssaint/UI/Settings/TextSnippetsSettings.swift, the Text Snippets engine expands short trigger strings into full text blocks—including dynamic date/time placeholders—anywhere you type. A searchable quick-menu organized into folders allows on-the-fly insertion of frequently used content.

The Shelf (File-Parking)

Sources/Vorssaint/UI/Shelf/ShelfView.swift implements a transient storage layer that appears near the cursor during drag operations. You can park files, text, and links on the Shelf, then drop them into their final destination later or share them directly via the macOS share sheet.

Command Bar

The universal Command Bar (Sources/Vorssaint/UI/CommandBar/CommandBarView.swift) provides a Spotlight-like interface (default shortcut ⌘K) capable of launching applications, inserting emojis, executing local scripts, and performing basic calculations from a single input field.

System Administration Tools

App Uninstaller

Sources/Vorssaint/Services/Uninstall/AppUninstaller.swift performs deep removal of applications by locating and trashing associated caches, preferences, containers, and helper daemons. Dropping an application onto the Uninstaller panel triggers a recursive search for related filesystem artifacts.

Homebrew Manager

Sources/Vorssaint/Services/Homebrew/HomebrewManager.swift wraps the Homebrew CLI, allowing you to search, install, and remove formulae and casks through a native GUI rather than Terminal commands.

Keep Awake and Display Control

• Keep Awake: Sources/Vorssaint/Services/KeepAwake/KeepAwakeService.swift prevents system sleep for a timer-defined period while optionally allowing the display to sleep or the lid to remain closed.
• Display Control: Sources/Vorssaint/Services/Display/DisplayControl.swift manages per-display brightness, toggles external monitors, and can push XDR panels beyond standard maximum brightness levels.

Super Key and Input Modification

Sources/Vorssaint/Services/SuperKey/SuperKeyService.swift remaps Caps-Lock or right-side modifiers into a configurable Super Key that can dispatch application shortcuts, switch input sources, or function as an Escape key.

Quick Toggles and Radial Menu

• Quick Toggles: Sources/Vorssaint/Services/QuickToggles.swift exposes one-click actions for Dark Mode, keyboard backlight, Trash emptying, and desktop icon visibility.
• Radial Menu: Sources/Vorssaint/UI/RadialMenu/RadialMenu.swift renders a circular wheel of favorite actions (applications, files, or scripts) around the cursor when a designated shortcut is held.

Summary

• Vorssaint-Utils is a macOS-only menu-bar application consolidating system tools into a unified SwiftUI interface.
• The architecture relies on ObservableObject services (e.g., AppVolumeMixer, SystemMonitor) to publish real-time state to UI panels.
• Core functionalities include per-application audio routing, hardware temperature monitoring, window snapping/layout, clipboard history, and a command-line interface.
• Administrative tools like the AppUninstaller and HomebrewManager automate system maintenance without Terminal access.
• The application operates privacy-first, processing media conversions and clipboard data locally without external services.

Frequently Asked Questions

Does Vorssaint-Utils require macOS-specific permissions to function?

Yes. Because Vorssaint-Utils interacts with system audio objects, window management APIs, and hardware sensors, it requires accessibility permissions for window snapping and control, as well as microphone access for the per-app volume mixer. The app requests these permissions on-demand when you first enable a feature, following the privacy-by-default principle outlined in the repository design.

Can Vorssaint-Utils be controlled entirely from the command line?

Partially. While the primary interface is graphical, Sources/Vorssaint/main.swift supports diagnostic flags including --selftest for internal diagnostics, --sensors for dumping raw hardware data, and --uninstall for complete removal. For programmatic control of services like the volume mixer, you import the Vorssaint framework in Swift and access shared instances like AppVolumeMixer.shared.

How does the System Monitor minimize CPU usage when panels are hidden?

The implementation in Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift uses an adaptive sampling cadence. When the menu-bar widget or system panel is not visible, the service reduces the frequency of calls to SMCClient.swift and other sensor interfaces, suspending expensive I/O operations until the UI demands fresh data.

Is Vorssaint-Utils open-source and free to modify?

Yes. The vorssaint/vorssaint-utils repository is open-source, allowing you to audit the Swift code, modify ObservableObject services, or extend the command-line interface in main.swift. The modular service architecture makes it straightforward to disable specific features by excluding the relevant source files from the build.

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