Core Features of Vorssaint-Utils: A Complete Guide to the Modular macOS Utility Hub

Vorssaint-utils is a modular macOS utility platform that exposes dozens of independent tools—ranging from window management to system monitoring—through a single menu-bar icon, with each feature defined in the AppFeature enum and dynamically activated via UserDefaults.

Unlike monolithic utility apps that force users to load every tool simultaneously, the core features of vorssaint-utils are architected around a feature hub design. This approach allows you to install only the utilities you need, conserving CPU, memory, and energy while maintaining a lightweight footprint. According to the vorssaint/vorssaint-utils source code, each capability is cataloged in Sources/Vorssaint/Core/FeatureCatalog.swift, grouped into logical categories, and governed by a permission system that requests only the specific macOS grants required for active features.

How the Feature Hub Architecture Works

The foundation of vorssaint-utils lies in the AppFeature enum, which serves as the single source of truth for every utility available in the app.

The AppFeature Enum

Located in FeatureCatalog.swift, the AppFeature enum defines stable identifiers for all utilities, their availability keys, enable flags, and required permissions. Each feature declares:

• availabilityKey – A DefaultsKey (stored in UserDefaults) that tracks whether the feature is installed
• enabledKeys – One or more Boolean keys that determine if the feature is currently active
• permissions – The specific macOS permissions (Accessibility, Screen Recording, etc.) required for operation

This declarative structure allows the app to calculate feature state dynamically. When you toggle a feature off or uninstall it, the corresponding availabilityKey is set to false, immediately freeing system resources.

Dynamic Activation and Permission Mapping

The hub checks both the availabilityKey and enabledKeys to determine if a feature should run. This design powers the permission-request flow: instead of demanding all permissions at launch, vorssaint-utils uses the activeFeatures(using:) method to identify which features are currently engaging a specific permission type (such as .accessibility or .screenRecording), then requests only those grants.

Core Features of Vorssaint-Utils by Category

The utilities are organized into seven logical groups within the Settings UI, each containing specific capabilities accessed via the AppFeature enum.

Windows & Dock Management

These features enhance macOS window switching and organization:

• AppFeature.switcher – An enhanced Command-Tab experience with live window thumbnails, replacing the native app switcher
• AppFeature.dockPreview – Hover-over window thumbnails that appear when hovering dock icons, providing visual previews before switching
• AppFeature.windowLayout – Snap windows to halves, thirds, corners, or custom grid positions using keyboard shortcuts or drag zones

Mouse & Keyboard Utilities

Input customization tools that modify macOS behavior:

• AppFeature.focusFollowsMouse – Automatically focuses windows when the cursor hovers over them, similar to X11 window managers
• AppFeature.smoothScroll and AppFeature.scrollInverter – Custom scrolling acceleration curves and direction inversion independent of system settings
• AppFeature.superKey – Remaps Caps Lock or right-side modifiers into a custom hyper key for complex shortcuts

Clipboard & File Management

Productivity tools for data manipulation:

• AppFeature.clipboardHistory – Persistent clipboard storage with pinning capabilities, image support, and automatic clearing intervals
• AppFeature.shelf – A temporary "parking" area for files, text snippets, and links, accessible via the menu bar
• AppFeature.urlCleaner – Automatically strips tracking parameters (UTMs, fbclid, etc.) from copied URLs

Sound Control

Advanced audio management beyond macOS defaults:

• AppFeature.mixer – Per-application volume control with the ability to boost audio past 100%, plus the option to hide inactive apps from the mixer
• AppFeature.soundOutputSwitcher – Rapid audio output switching via keyboard shortcut, bypassing the Sound preference pane

Energy & Display

Power management and screen adjustment tools:

• AppFeature.keepAwake – Prevents sleep through multiple methods including mouse jiggling or keeping the lid open during clamshell mode
• AppFeature.brightness and AppFeature.extraBrightness – Display brightness controls that can push XDR displays (like Pro Display XDR or MacBook Pro Liquid Retina XDR) past their normal maximum nits

Tools & Launchers

System utilities and automation:

• AppFeature.commandBar – A universal launcher supporting actions, app opening, text snippet insertion, and custom workflows
• AppFeature.screenshot and AppFeature.screenRecorder – Screen capture with area selection, recording with audio track selection, and OCR text extraction
• AppFeature.cleaner and AppFeature.uninstaller – Cache and log sweeping, plus complete application removal including associated files

System Monitor

Hardware monitoring with visualization:

• AppFeature.monitorCPU, AppFeature.monitorMemory, AppFeature.monitorDisk, AppFeature.monitorPower, and AppFeature.monitorNetwork – Live graphing of system metrics with configurable alert thresholds
• AppFeature.fanControl (beta) – Manual fan speed curve adjustment for thermal management

Working with Features Programmatically

The vorssaint-utils codebase exposes a public API for inspecting and toggling features. You can query feature states or enable utilities programmatically using Swift.

Querying Feature State

To check if a feature is active, verify both its availability and enabled status:

import Foundation
import Vorssaint

func isFeatureActive(_ feature: AppFeature) -> Bool {
    // Check if feature is installed via availabilityKey
    let available = UserDefaults.standard.bool(forKey: feature.availabilityKey)
    
    // Check if at least one enable key is true (empty array means always enabled)
    let enabled = feature.enabledKeys.isEmpty ||
        feature.enabledKeys.contains { UserDefaults.standard.bool(forKey: $0) }
    
    return available && enabled
}

// Example usage
let switcherActive = isFeatureActive(.switcher)
print("Switcher active: \(switcherActive)")

Enabling Features Programmatically

You can activate features by setting their availability and enable keys:

func enableFeature(_ feature: AppFeature) {
    // Mark as available/installed
    UserDefaults.standard.set(true, forKey: feature.availabilityKey)
    
    // Enable primary toggle
    if let primaryKey = feature.enabledKeys.first {
        UserDefaults.standard.set(true, forKey: primaryKey)
    }
}

// Enable the shelf utility
enableFeature(.shelf)

Checking Permission Requirements

To identify which active features require specific macOS permissions:

let activeAccessibility = AppFeature.activeFeatures(
    using: .accessibility,
    defaults: .standard
)
print("Features using Accessibility: \(activeAccessibility.map { $0.rawValue })")

Summary

The core features of vorssaint-utils demonstrate a privacy-first, modular approach to macOS system utilities:

• Modular Architecture – The AppFeature enum in FeatureCatalog.swift defines every utility with availabilityKey and enabledKeys for dynamic loading
• Seven Feature Categories – Windows & Dock, Mouse & Keyboard, Clipboard & Files, Sound, Energy & Display, Tools, and System Monitor
• Resource Efficiency – Features can be individually uninstalled, immediately freeing CPU and memory resources
• Privacy-by-Design – Permission mapping ensures only required macOS grants (Accessibility, Screen Recording, etc.) are requested for active features
• Local-First – No telemetry; all data and preferences remain on the local machine through UserDefaults

Frequently Asked Questions

How does vorssaint-utils handle permissions compared to other utility apps?

Unlike traditional macOS utilities that request all permissions at launch, vorssaint-utils uses the permissions property of the AppFeature enum to declare required grants per feature. The activeFeatures(using:) method calculates which features are currently enabled for a specific permission type (such as .accessibility or .screenRecording), and the app requests only those specific macOS grants when needed. This minimizes the attack surface and respects user privacy by avoiding unnecessary system access.

Can I uninstall individual features to free up system resources?

Yes. Each feature in FeatureCatalog.swift has an availabilityKey stored in UserDefaults. Setting this key to false marks the feature as uninstalled, which immediately stops its background processes and frees associated CPU, memory, and energy resources. This modular approach allows you to run a lightweight configuration with only the tools you actively use.

Where is the feature configuration stored in the source code?

Feature definitions reside in Sources/Vorssaint/Core/FeatureCatalog.swift, which contains the AppFeature enum defining all utilities, their grouping logic (FeatureGroup), and permission requirements (AppPermission). UI strings for these features are localized in FeatureStrings.swift, while the application entry point in main.swift initializes the menu-bar icon and injects the feature hub into the user interface.

Is there a programmatic way to check which features are slowing down my system?

While vorssaint-utils does not include a built-in performance profiler, you can use the AppFeature API to audit active features. By iterating through AppFeature.allCases and checking isFeatureActive() for each, or by using activeFeatures(using:) to see which utilities require specific high-impact permissions (like Screen Recording), you can identify and disable resource-intensive modules. The System Monitor features (monitorCPU, monitorMemory) also provide real-time graphs to observe the impact of enabling specific utilities.

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