# What Utilities Are Included in vorssaint‑utils? A Complete Breakdown of This macOS Utility Suite

> Explore vorssaint-utils a macOS utility suite offering over 30 tools like volume mixing window snapping and clipboard history integrated into a single menu bar app.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: deep-dive
- Published: 2026-09-05

---

**vorssaint‑utils** is a modular macOS utility suite that bundles over 30 system tools—from volume mixing and window snapping to clipboard history and Homebrew management—into a single menu‑bar application with optional, on‑demand features.

The `vorssaint/vorssaint‑utils` repository organizes every capability as an independent Swift service. Users enable only what they need through a **Features** hub, keeping resource usage minimal. Below is a comprehensive tour of every utility category, with direct source file references showing exactly where each feature lives in the codebase.

---

## Sound Utilities: Per‑App Audio Control and Output Management

Audio in vorssaint‑utils goes far beyond macOS's global volume slider. The suite provides granular, per‑application control with hardware routing shortcuts.

### Volume Mixer with Per‑App Sliders

The **Volume Mixer** ([`MenuPanel/SystemSection.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MenuPanel/SystemSection.swift)) renders independent volume faders for every running audio source. Developers can interact with this programmatically through the shared `WindowLayoutService`:

```swift
import Vorssaint

// Set Music.app to 80% volume without affecting system audio
if let mixer = WindowLayoutService.shared?.volumeMixer {
    try? mixer.setVolume(80, forAppBundleID: "com.apple.music")
}

```

### Per‑Application Output Routing

Route specific apps to different audio devices—send Music.app to headphones while keeping system alerts on built‑in speakers. The underlying logic resides in [`WindowServerSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowServerSupport.swift), which interfaces with macOS's audio object APIs.

### Output Switcher and Microphone Tools

- **Output Switcher**: Cycle playback devices via global shortcut ([`UpdateService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateService.swift))
- **Microphone Management**: Pin favorite inputs and mute all mics system‑wide ([`SystemShortcutTakeover.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SystemShortcutTakeover.swift))
- **Music App Blocker**: Prevent Music.app from auto‑launching on Bluetooth connect ([`WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift))

---

## System Monitoring: Live Hardware Metrics and Alerts

The monitoring stack visualizes CPU, GPU, memory, temperature, and network data in real‑time graphs.

### Live Performance Graphs

[`PanelWindowLayoutView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/PanelWindowLayoutView.swift) hosts the rendering layer for history graphs tracking:
- CPU and GPU utilization
- Memory pressure and swap usage
- Network throughput with integrated speed tests ([`UpdateServiceSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateServiceSupport.swift))

### Temperature, Fan Control, and Alerting

| Feature | Implementation |
|---|---|
| Temperature sensors | Derived from IOKit, displayed in monitoring panel |
| Fan speed control | [`FanControlService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlService.swift) (beta feature with optional UI) |
| Threshold alerts | [`UpdateShowcaseMedia.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateShowcaseMedia.swift) handles CPU, temperature, battery, and disk‑space notifications |

The fan control module includes a separate helper binary at [`Sources/FanControlHelper/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift) for low‑level hardware access that requires elevated privileges.

---

## Window and Dock Management: Advanced Switching and Layout

vorssaint‑utils replaces and extends macOS's built‑in windowing behaviors with programmable snapping, richer app switching, and dock enhancements.

### Window Layout Service

[`WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutService.swift) is the core engine for window manipulation. It supports:

- **Snap zones**: Halves, thirds, corners, and custom grids
- **Multi‑display moves**: Throw windows between monitors with shortcuts
- **Presets**: Save and recall favorite arrangements

```swift
// Snap frontmost window to left half of screen
await WindowLayoutService.shared?.snapFrontWindow(to: .leftHalf)

```

### App Switcher with Live Thumbnails

The custom ⌘‑Tab replacement ([`SwitcherView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SwitcherView.swift)) shows live window previews instead of static icons, with configurable activation rules.

### Dock Enhancements

| Feature | Source File |
|---|---|
| Hover‑over window thumbnails | [`DockPreviewPanelView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/DockPreviewPanelView.swift) |
| Click actions (minimize, hide, cycle) | [`WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) |
| Quit on Close / Quit‑Protection rules | [`UninstallerView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UninstallerView.swift) |

---

## Keyboard and Mouse Utilities: Text Expansion and Input Customization

Input devices gain programmable behaviors including snippet expansion, scrolling modifications, and modifier key remapping.

### Text Snippets with Variable Support

[`SnippetLibraryView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SnippetLibraryView.swift) implements trigger‑based expansion. Snippets support dynamic variables (dates, clipboard, cursor positioning):

```swift
// Add a snippet that expands "addr" to a full address
SnippetLibrary.shared.addSnippet(
    trigger: "addr",
    expansion: "123 Main St, Springfield"
)

```

### Pointer and Scrolling Modifications

- **Smooth Scrolling toggle**: Enable/disable macOS's animated scroll ([`ScrollInverter.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ScrollInverter.swift))
- **Pointer Acceleration control**: Adjust or disable cursor acceleration curves
- **Focus‑Follows‑Mouse**: Auto‑focus windows on hover without clicking ([`MouseClickDebounceService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MouseClickDebounceService.swift))

### Advanced Button and Key Mapping

[`HotkeyManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/HotkeyManager.swift) registers global shortcuts system‑wide, while [`SystemShortcutTakeoverSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SystemShortcutTakeoverSupport.swift) allows redefining native macOS shortcuts—including repurposing **Caps Lock as a "Super Key"** modifier.

---

## Clipboard, Files, and Link Utilities

The suite provides a full clipboard manager plus tools for file handling and URL cleaning.

### Clipboard History and Management

| Feature | Implementation |
|---|---|
| history with search, pinning, favorites | [`ClipboardHistorySearch.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistorySearch.swift) (tested in [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift)) |
| Auto‑clear with configurable delay | [`ClipboardAutoClearSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardAutoClearSupport.swift) |
| Paste as Plain Text shortcut | [`UpdateService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateService.swift) |

### File and Link Tools

- **Shelf**: Temporary drop zone for files and text snippets ([`Uninstall/AppPickerView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Uninstall/AppPickerView.swift))
- **Finder Shortcuts**: Cut/paste (⌘X/⌘V), F2 rename, image‑to‑PNG conversion ([`PanelHomebrewView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/PanelHomebrewView.swift))
- **Clean URL**: Strip tracking parameters from copied links ([`URLCleanerService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/URLCleanerService.swift))
- **Disk‑Image Installer**: One‑click `.dmg` app installation ([`UninstallerSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UninstallerSupport.swift))

---

## Everyday Tools: Launchers, Capture, and System Maintenance

This category contains the most diverse set of utilities for productivity, media, and system hygiene.

### Command Bar and Quick Access

| Tool | Function | Source |
|---|---|---|
| **Command Bar** | Universal launcher and command runner | [`CommandBar.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/CommandBar.swift) |
| **Quick Panel** | Floating palette of favorite toggles | [`QuickTogglesSection.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/QuickTogglesSection.swift) |
| **Radial Menu** | Wheel of actions surrounding cursor | [`ShortcutRecorderButton.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ShortcutRecorderButton.swift) |

### Screen Capture and Media Tools

The recording pipeline centers on [`ScreenRecorderService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ScreenRecorderService.swift):

```swift
let recorder = ScreenRecorderService.shared

// Record 10 seconds of audio‑only capture
await recorder.startCapture(audioOnly: true)
try await Task.sleep(nanoseconds: 10_000_000_000)
await recorder.stopCapture { url in
    print("Saved to:", url.path)
}

```

Supporting files:
- [`RecorderEditorController.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/RecorderEditorController.swift): Trim and edit captures
- [`RecorderExport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/RecorderExport.swift): Export to MP4, GIF, and other formats
- [`VideoThumbnailer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/VideoThumbnailer.swift): Video compression, GIF creation, image batch processing

### Additional Productivity Utilities

- **Camera Preview**: Floating selfie window ([`CameraPreview.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/CameraPreview.swift))
- **Scratchpad**: Markdown‑aware floating notes ([`Scratchpad.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Scratchpad.swift))
- **Color Picker**: Pixel inspector with copy‑as‑code output ([`ColorPicker.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ColorPicker.swift))
- **Cleaning Mode**: Lock keyboard and optionally dim screen for physical cleaning ([`CleaningMode.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/CleaningMode.swift))

### System Maintenance

| Tool | Purpose | Source |
|---|---|---|
| **App Updates** | Unified checker for Homebrew, App Store, direct downloads | [`UpdateService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/UpdateService.swift) |
| **Cleaner** | Purge caches, logs, messaging downloads | [`Cleaner.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Cleaner.swift) |
| **Uninstaller** | Deep app removal including residue files | [`AppUninstaller.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/AppUninstaller.swift) |
| **Homebrew Manager** | Search, install, remove formulae and casks | [`HomebrewManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/HomebrewManager.swift) |

---

## Energy and Display Utilities

Power users gain granular control over sleep behavior, display brightness, and Bluetooth states.

### Keep‑Awake and Sleep Management

[`KeepAwakeManager.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/KeepAwakeManager.swift) supports timer‑based stay‑awake and lid‑closed operation:

```swift
// Prevent sleep for 30 minutes
await KeepAwakeManager.shared.startTimer(minutes: 30)

```

### Display Control

- **Per‑display brightness and power**: Individual monitor on/off with native OSD ([`BrightnessService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/BrightnessService.swift))
- **Extra Brightness**: Push XDR panels past default maximum nits ([`ExtraBrightnessService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ExtraBrightnessService.swift))

### Bluetooth Sleep Behavior

[`BluetoothSleepSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/BluetoothSleepSupport.swift) automatically disables Bluetooth when sleeping and re‑enables on wake—useful for preserving battery with peripherals that wake the machine unnecessarily.

---

## Architectural Design: How vorssaint‑utils Stays Modular

The codebase enforces strict separation between services and UI, enabling the optional‑feature model.

### Service‑Oriented Structure

Every utility domain lives under `Sources/Vorssaint/Services/` with a clean public API:

```

Sources/Vorssaint/
├── Services/
│   ├── WindowLayout/WindowLayoutService.swift
│   ├── FanControl/FanControlService.swift
│   ├── Recorder/ScreenRecorderService.swift
│   ├── Homebrew/HomebrewManager.swift
│   ├── Uninstall/AppUninstaller.swift
│   └── ...

```

### Dynamic UI Assembly

`PanelHome` assembles the menu‑bar dropdown from enabled sections (`SystemSection`, `PowerSection`, `PanelLayout`, etc.) rather than loading fixed panels.

### Permission‑Aware Activation

macOS permissions (Accessibility, Screen Recording, Full Disk Access) are requested lazily when a feature first needs them—not at launch. The UI surfaces permission status per‑feature.

### Global State and Shortcuts

- **Settings**: `UserDefaults` keys like `Defaults.allowedClipboardHistoryLimits` shared across services
- **Hotkeys**: `HotkeyManager` registers global shortcuts; `SystemShortcutTakeover` rebinds native macOS shortcuts per‑app

---

## Summary

vorssaint‑utils consolidates over 30 macOS utilities into one modular menu‑bar application:

- **Sound**: Per‑app volume, output routing, microphone tools, Music.app blocking
- **System Monitoring**: CPU/GPU/memory graphs, temperature/fan control, alerts
- **Windows & Dock**: Snap layouts, enhanced ⌘‑Tab, dock previews, quit rules
- **Keyboard & Mouse**: Text snippets, smooth scrolling, focus‑follows‑mouse, Super Key
- **Clipboard & Files**: History with search, shelf, URL cleaner, Finder shortcuts
- **Everyday Tools**: Command bar, screen recorder, scratchpad, color picker, Homebrew manager, cleaner, uninstaller
- **Energy & Display**: Keep‑awake timer, per‑display brightness, extra XDR brightness, Bluetooth sleep control

All features are optional and installable on demand through the Features hub. Source files are organized under `Sources/Vorssaint/Services/` and `Sources/Vorssaint/UI/`, with public APIs accessible to developers integrating the framework.

---

## Frequently Asked Questions

### How do I enable or disable specific utilities in vorssaint‑utils?

Open the **Features** hub from the menu bar. Each utility appears as a toggleable module; disabling a module unloads its service and removes its UI components. This design ensures only active code consumes CPU and memory.

### What macOS permissions does vorssaint‑utils require?

Permissions vary by feature: **Accessibility** for window snapping and app switching, **Screen Recording** for capture and color picker, **Full Disk Access** for cleaner and uninstaller operations, and **Microphone** for audio recording. The app requests each permission lazily when first needed, not at launch.

### Can I use vorssaint‑utils utilities programmatically in my own Swift code?

Yes. Service classes expose public APIs as shown in the code examples. Import the `Vorssaint` module and access shared instances like `WindowLayoutService.shared`, `KeepAwakeManager.shared`, or `SnippetLibrary.shared`. Refer to the source files under `Sources/Vorssaint/Services/` for complete method signatures.

### Is the fan control feature safe to use?

Fan control is marked beta and operates through [`FanControlService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FanControlService.swift) with a privileged helper binary ([`Sources/FanControlHelper/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/FanControlHelper/main.swift)). The UI surfaces temperature readings before allowing manual adjustments, and settings persist only until manually changed or the app restarts.