Main Features of Vorssaint‑Utils: Modular macOS Utilities in a Single Menu‑Bar App

Vorssaint‑utils is a modular macOS utility suite that exposes dozens of independent tools—window management, clipboard history, sound mixing, and system monitoring—through a single menu‑bar icon, with each feature defined in the AppFeature enum and dynamically loaded via FeatureCatalog.swift.

Vorssaint‑utils (vorssaint/vorssaint-utils) organizes its capabilities around a central feature hub architecture. Rather than monolithic bloat, the application exposes a catalog of optional utilities that users can install, enable, or remove on demand. This design keeps resource usage minimal while providing advanced window management, input customization, and system monitoring tools.

Feature Catalog Overview

The AppFeature enum in Sources/Vorssaint/Core/FeatureCatalog.swift defines every available utility. Features are grouped logically for the Settings UI and can be toggled independently. Below are the seven primary categories and their representative capabilities.

Windows & Dock

This group enhances macOS window navigation and the Dock experience:

• App Switcher (AppFeature.switcher): A richer Command‑Tab experience displaying live window thumbnails
• Dock Preview (AppFeature.dockPreview): Hover‑over window thumbnails activated via Accessibility APIs
• Window Layout (AppFeature.windowLayout): Snap windows to halves, thirds, or corners using keyboard shortcuts

Mouse & Keyboard

Input customization utilities that modify pointer behavior and modifier keys:

• Focus‑Follows‑Mouse (AppFeature.focusFollowsMouse): Automatically activate windows under the cursor
• Smooth Scrolling (AppFeature.smoothScroll) and Scroll Inverter (AppFeature.scrollInverter): Customize scroll wheel physics and direction
• Super Key (AppFeature.superKey): Remap Caps Lock or right‑side modifiers into custom shortcuts

Clipboard & Files

Data management tools for the pasteboard and transient file storage:

• Clipboard History (AppFeature.clipboardHistory): Persistent history with pinning, image support, and automatic clearing rules
• Shelf (AppFeature.shelf): A temporary "parking" area for files, text snippets, and links
• URL Cleaner (AppFeature.urlCleaner): Automatically strip tracking parameters from copied URLs

Sound

Audio routing and per‑application volume control:

• Volume Mixer (AppFeature.mixer): Per‑app volume adjustment, boost past 100 %, and hiding inactive applications
• Sound Output Switcher (AppFeature.soundOutputSwitcher): Rapidly switch audio outputs using global shortcuts

Energy & Display

Hardware control utilities for sleep prevention and screen brightness:

• Keep Awake (AppFeature.keepAwake): Prevent system sleep, jiggle the mouse, or maintain operation with the lid closed
• Brightness & Extra Brightness (AppFeature.brightness, AppFeature.extraBrightness): Standard adjustment plus XDR panel over‑driving for HDR displays

Tools

General productivity and maintenance utilities:

• Command Bar (AppFeature.commandBar): Universal launcher supporting actions, app launching, and text snippet insertion
• Screen Capture & Recorder (AppFeature.screenshot, AppFeature.screenRecorder): Screenshots, area recordings, OCR text recognition, and audio‑track selection
• Cleaner & Uninstaller (AppFeature.cleaner, AppFeature.uninstaller): Cache sweeping, log deletion, and complete application removal

System Monitor

Live hardware telemetry with alerting capabilities:

• CPU, Memory, Disk, Power & Network monitors (AppFeature.monitorCPU, AppFeature.monitorMemory, etc.): Real‑time graphs with configurable alert thresholds
• Fan Control (beta) (AppFeature.fanControl): Manual fan speed curve adjustment

Architecture and Dynamic Activation

Vorssaint‑utils uses a dynamic activation system to load only the features you need. In FeatureCatalog.swift, each AppFeature declares its availabilityKey and enabledKeys, which map to UserDefaults entries.

Permission Mapping

Each feature declares required macOS permissions via the permissions property. For example, the App Switcher requires Accessibility access, while Dock Preview needs Screen Recording permissions. The hub requests only the grants necessary for currently active features, enforcing a privacy‑first approach with no telemetry.

Resource Management

When a feature is disabled, its availabilityKey is set to false in UserDefaults.standard, immediately freeing CPU, memory, and energy resources. This granular control prevents background bloat from unused utilities.

Programmatic Feature Control

Developers and power users can inspect or toggle features via the public Swift API defined in FeatureCatalog.swift.

Checking Feature Status

The availabilityKey property returns the UserDefaults key tracking installation status, while enabledKeys contains the Boolean flags that activate the feature:

import Vorssaint

func isFeatureActive(_ feature: AppFeature) -> Bool {
    let available = UserDefaults.standard.bool(forKey: feature.availabilityKey)
    let enabled = feature.enabledKeys.isEmpty ||
        feature.enabledKeys.contains { UserDefaults.standard.bool(forKey: $0) }
    return available && enabled
}

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

Enabling Features Programmatically

To install and activate a feature via script or extension:

func enableFeature(_ feature: AppFeature) {
    UserDefaults.standard.set(true, forKey: feature.availabilityKey)
    if let primaryKey = feature.enabledKeys.first {
        UserDefaults.standard.set(true, forKey: primaryKey)
    }
}

enableFeature(.shelf)

Filtering by Permission

Identify which active features require specific macOS permissions using activeFeatures(using:):

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

Key Implementation Files

The feature system is distributed across four core files:

• Sources/Vorssaint/Core/FeatureCatalog.swift: Defines the AppFeature enum, feature groups, permission mappings, and activation logic
• Sources/Vorssaint/Core/FeatureStrings.swift: Localized UI strings for feature titles, captions, and toggle labels
• Sources/Vorssaint/main.swift: Application entry point that initializes the menu‑bar icon and injects the feature hub
• Sources/Vorssaint/Core/SettingsCategoryStrings.swift: Localized names for Settings sections (Essentials, Windows Controls, etc.)

Summary

• Vorssaint‑utils exposes seven feature groups containing over twenty distinct utilities, from window snapping to fan control
• Features are defined in the AppFeature enum and grouped via FeatureGroup for the Settings UI
• Dynamic activation uses availabilityKey and enabledKeys stored in UserDefaults, ensuring unused features consume zero resources
• Permission requirements are declared per‑feature in permissions, allowing granular macOS grant requests
• The public API supports programmatic inspection via isFeatureActive() and activeFeatures(using:) methods

Frequently Asked Questions

How do I check if a specific vorssaint‑utils feature is currently running?

Use the isFeatureActive(_:) helper pattern shown in FeatureCatalog.swift. This checks both the availabilityKey (installation status) and enabledKeys (activation flags) in UserDefaults.standard. A feature is only considered active when both conditions return true.

Can I use vorssaint‑utils features without installing all of them?

Yes. Vorssaint‑utils uses a modular architecture where each utility is optional. Features are loaded dynamically based on their availabilityKey values. Uninstalling a feature by setting its availability to false immediately releases its memory and CPU resources.

Which vorssaint‑utils features require Accessibility permissions?

Features that manipulate window focus or keyboard input—specifically the App Switcher (AppFeature.switcher), Focus‑Follows‑Mouse (AppFeature.focusFollowsMouse), and Super Key (AppFeature.superKey)—require Accessibility access. You can query exactly which active features need this permission by calling AppFeature.activeFeatures(using: .accessibility, defaults: .standard).

Where are feature availability settings stored in vorssaint‑utils?

Availability and enable states persist via UserDefaults using keys defined by the availabilityKey and enabledKeys properties of each AppFeature. For example, the shelf feature stores its installation status under the key returned by AppFeature.shelf.availabilityKey, while its on/off state maps to the strings in AppFeature.shelf.enabledKeys.

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