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

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) renders independent volume faders for every running audio source. Developers can interact with this programmatically through the shared WindowLayoutService:

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, which interfaces with macOS's audio object APIs.

Output Switcher and Microphone Tools

• Output Switcher: Cycle playback devices via global shortcut (UpdateService.swift)
• Microphone Management: Pin favorite inputs and mute all mics system‑wide (SystemShortcutTakeover.swift)
• Music App Blocker: Prevent Music.app from auto‑launching on Bluetooth connect (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 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)

Temperature, Fan Control, and Alerting

Feature	Implementation
Temperature sensors	Derived from IOKit, displayed in monitoring panel
Fan speed control	FanControlService.swift (beta feature with optional UI)
Threshold alerts	UpdateShowcaseMedia.swift handles CPU, temperature, battery, and disk‑space notifications

The fan control module includes a separate helper binary at 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 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

// 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) shows live window previews instead of static icons, with configurable activation rules.

Dock Enhancements

Feature	Source File
Hover‑over window thumbnails	DockPreviewPanelView.swift
Click actions (minimize, hide, cycle)	WindowGestureControls.swift
Quit on Close / Quit‑Protection rules	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 implements trigger‑based expansion. Snippets support dynamic variables (dates, clipboard, cursor positioning):

// 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)
• Pointer Acceleration control: Adjust or disable cursor acceleration curves
• Focus‑Follows‑Mouse: Auto‑focus windows on hover without clicking (MouseClickDebounceService.swift)

Advanced Button and Key Mapping

HotkeyManager.swift registers global shortcuts system‑wide, while 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 (tested in Tests/MetricsTests.swift)
Auto‑clear with configurable delay	ClipboardAutoClearSupport.swift
Paste as Plain Text shortcut	UpdateService.swift

File and Link Tools

• Shelf: Temporary drop zone for files and text snippets (Uninstall/AppPickerView.swift)
• Finder Shortcuts: Cut/paste (⌘X/⌘V), F2 rename, image‑to‑PNG conversion (PanelHomebrewView.swift)
• Clean URL: Strip tracking parameters from copied links (URLCleanerService.swift)
• Disk‑Image Installer: One‑click .dmg app installation (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
Quick Panel	Floating palette of favorite toggles	QuickTogglesSection.swift
Radial Menu	Wheel of actions surrounding cursor	ShortcutRecorderButton.swift

Screen Capture and Media Tools

The recording pipeline centers on ScreenRecorderService.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: Trim and edit captures
• RecorderExport.swift: Export to MP4, GIF, and other formats
• VideoThumbnailer.swift: Video compression, GIF creation, image batch processing

Additional Productivity Utilities

• Camera Preview: Floating selfie window (CameraPreview.swift)
• Scratchpad: Markdown‑aware floating notes (Scratchpad.swift)
• Color Picker: Pixel inspector with copy‑as‑code output (ColorPicker.swift)
• Cleaning Mode: Lock keyboard and optionally dim screen for physical cleaning (CleaningMode.swift)

System Maintenance

Tool	Purpose	Source
App Updates	Unified checker for Homebrew, App Store, direct downloads	UpdateService.swift
Cleaner	Purge caches, logs, messaging downloads	Cleaner.swift
Uninstaller	Deep app removal including residue files	AppUninstaller.swift
Homebrew Manager	Search, install, remove formulae and casks	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 supports timer‑based stay‑awake and lid‑closed operation:

// 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)
• Extra Brightness: Push XDR panels past default maximum nits (ExtraBrightnessService.swift)

Bluetooth Sleep Behavior

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 with a privileged helper binary (Sources/FanControlHelper/main.swift). The UI surfaces temperature readings before allowing manual adjustments, and settings persist only until manually changed or the app restarts.

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