How to Configure Vorssaint-Utils: Complete UserDefaults and Settings Guide

Vorssaint-utils stores every user-adjustable option in macOS UserDefaults using keys defined in Sources/Vorssaint/Core/Defaults.swift, enabling both GUI-based and programmatic configuration that persists instantly across app launches.

The vorssaint-utils repository provides a macOS utility suite where all customization flows through a centralized defaults system. Whether you adjust settings through the SwiftUI preferences interface or modify values directly via code, every change writes to the standard macOS preferences domain com.vorssaint.utils. This architecture ensures immediate persistence without requiring manual file editing or restart sequences.

Where Vorssaint-Utils Stores Configuration

All configuration values live in UserDefaults.standard under the bundle identifier com.vorssaint.utils. The central enumeration of valid keys resides in Sources/Vorssaint/Core/Defaults.swift, which serves as the single source of truth for both the application services and the Settings UI.

When vorssaint-utils launches, it reads initial values from the macOS preferences plist. The SwiftUI views under Sources/Vorssaint/UI/Settings/ bind directly to these UserDefaults keys, creating a reactive two-way sync: user interactions update storage immediately, and programmatic changes reflect instantly in the interface.

Configuration Categories and UI Locations

Vorssaint-utils organizes settings into logical groups, each managed by specific SwiftUI views and underlying service layers.

Panels and Layout Visibility

The panel system controls which utility panels appear in the interface. Settings for panel visibility are managed in Sources/Vorssaint/UI/Settings/PanelLayout.swift, with boolean flags like DefaultsKey.panelUtilitiesEnabled determining whether specific panels render.

Global Shortcuts

Window management shortcuts are configured in Sources/Vorssaint/UI/Settings/ShortcutsSettings.swift. This view manages keys including:

• DefaultsKey.windowLayoutShortcutsEnabled – Toggles directional window snapping
• DefaultsKey.windowGestureEnabled – Enables gesture-based window control
• DefaultsKey.windowDirectionalShortcut – Stores the specific key combination string (e.g., "⌥⌘←")

The WindowLayoutService (found in Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift) polls these defaults before executing shortcut actions.

App and Volume Exclusions

Exclusion lists prevent specific apps or volumes from triggering certain features. Sources/Vorssaint/UI/Settings/WindowPreviewExclusionsList.swift manages DefaultsKey.windowPreviewExcludedApps as a string array, while disk exclusions reside in sibling files using DefaultsKey.diskEjectExcludedVolumes.

Radial Menu Profiles

The radial launcher configuration stores complex data structures in Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift. Unlike simple booleans, radial menu profiles use DefaultsKey.radialMenuProfiles with Data serialization to persist dictionary or array structures.

Keep-Awake Automation

The keep-awake feature, controlled via Sources/Vorssaint/UI/Settings/KeepAwakeAutomationView.swift, stores bundle identifiers in DefaultsKey.keepAwakeRunningAppBundleIDs. This string array defines which running applications prevent display sleep.

Update Behavior

Automatic update settings live in Sources/Vorssaint/Services/Update/UpdateService.swift, checking DefaultsKey.autoCheckUpdates on launch and respecting media override flags stored in DefaultsKey.updateShowcaseMediaOverride.

Programmatic Configuration

You can modify vorssaint-utils settings directly from Swift scripts or external modules without launching the GUI. All changes use the same DefaultsKey constants defined in the core module.

Enable window gestures via code:

import Foundation

// Enable window-gesture shortcuts
UserDefaults.standard.set(true, forKey: DefaultsKey.windowGestureEnabled)

Add an application to the window preview exclusion list:

var excluded = UserDefaults.standard.stringArray(forKey: DefaultsKey.windowPreviewExcludedApps) ?? []
excluded.append("com.example.SomeApp")
UserDefaults.standard.set(excluded, forKey: DefaultsKey.windowPreviewExcludedApps)

Configure keep-awake for Safari:

let bundleID = "com.apple.Safari"
var ids = UserDefaults.standard.stringArray(forKey: DefaultsKey.keepAwakeRunningAppBundleIDs) ?? []
if !ids.contains(bundleID) { ids.append(bundleID) }
UserDefaults.standard.set(ids, forKey: DefaultsKey.keepAwakeRunningAppBundleIDs)

Disable the radial menu entirely:

UserDefaults.standard.set(false, forKey: DefaultsKey.radialMenuEnabled)

Reset specific shortcuts to factory defaults by removing the keys:

UserDefaults.standard.removeObject(forKey: DefaultsKey.windowLayoutShortcutsEnabled)
UserDefaults.standard.removeObject(forKey: DefaultsKey.windowGestureEnabled)
UserDefaults.standard.removeObject(forKey: DefaultsKey.windowEdgeSnapEnabled)

How Settings Changes Take Effect

Vorssaint-utils implements immediate configuration propagation through two mechanisms. First, SwiftUI views bind directly to UserDefaults values using property wrappers, ensuring UI components refresh automatically when underlying data changes. Second, background services such as WindowLayoutService subscribe to UserDefaults.didChangeNotification or poll values during event handling, allowing runtime behavior modification without restarts.

When you invoke UserDefaults.standard.set(_:forKey:), the system writes to the macOS preferences domain com.vorssaint.utils immediately. This persistent storage ensures configuration survives application termination and system reboots, loading automatically on the next vorssaint-utils launch.

Summary

• Storage location: All settings reside in UserDefaults.standard under the bundle identifier com.vorssaint.utils.
• Key definitions: The DefaultsKey enum in Sources/Vorssaint/Core/Defaults.swift centralizes all valid configuration keys.
• UI binding: SwiftUI views in Sources/Vorssaint/UI/Settings/ bind directly to UserDefaults for real-time synchronization.
• Service integration: Components like WindowLayoutService and UpdateService read defaults dynamically to drive behavior.
• Programmatic access: External Swift code can import Foundation and manipulate the same keys using standard UserDefaults API calls.
• Immediate persistence: Changes apply instantly and survive relaunches without additional code implementation.

Frequently Asked Questions

Where are vorssaint-utils settings saved on disk?

Vorssaint-utils writes configuration to the standard macOS UserDefaults system under the domain com.vorssaint.utils. macOS stores this data in a plist file within ~/Library/Preferences/, though you should interact with these values through the UserDefaults API rather than editing the file directly to prevent corruption.

Can I configure vorssaint-utils without opening the GUI?

Yes. Any Swift script or macOS application can modify vorssaint-utils settings by importing Foundation and calling UserDefaults.standard.set(_:forKey:) with the appropriate DefaultsKey values. Changes take effect immediately because the running vorssaint-utils process listens for UserDefaults notifications or polls values during operation.

How do I reset vorssaint-utils to default settings?

Remove specific keys using UserDefaults.standard.removeObject(forKey:) with the target DefaultsKey enumeration member, or delete the entire com.vorssaint.utils domain from ~/Library/Preferences/com.vorssaint.utils.plist while the application is closed. The next launch will regenerate defaults for any missing keys.

Which file contains the UserDefaults keys for vorssaint-utils?

All UserDefaults keys are defined as static constants in Sources/Vorssaint/Core/Defaults.swift. This file serves as the authoritative reference for every configurable option supported by the application, including booleans for feature toggles, strings for shortcuts, and string arrays for exclusion lists.

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