Known Issues with Vorssaint-Utils: Common Problems and Fixes

Yes, known issues with vorssaint-utils primarily involve macOS privacy permissions, Gatekeeper warnings, and occasional UI freezes, most of which are resolved through specific troubleshooting steps documented in the repository.

Vorssaint-utils is a Swift-based macOS menu-bar application that bundles dozens of independent utilities—including a volume mixer, app switcher, and screen capture tools—each enabled through feature flags. Because the app's functionality is tightly coupled to macOS privacy permissions, many known issues with vorssaint-utils stem from permission handling or edge-case bugs in the Accessibility and Screen Recording APIs, as tracked in docs/TROUBLESHOOTING.md and CHANGELOG.md.

Permission and Security Issues

Most functional failures trace back to macOS privacy controls and code signing verification handled in Sources/Vorssaint/Core/Permissions.swift and Sources/Vorssaint/App/AppDelegate.swift.

Gatekeeper and Code Signature Warnings

When launching vorssaint-utils, macOS may refuse to start the app or display a Gatekeeper warning. This occurs because the operating system verifies the code signature and notarization of the binary, which is managed in Package.swift during the build process. The README documents the workaround: right-click the app and select Open to bypass the warning for unsigned local builds.

Privacy Permissions Not Sticking

A common issue involves toggling permissions in System Settings that appear to have no effect or revert after relaunch. This happens because macOS caches the old signature, and the permission watcher in Sources/Vorssaint/Core/Permissions.swift does not automatically refresh after signature changes. To resolve this, remove the old entry from System Settings and re-grant the permission, or reset the permission cache using tccutil.

Silent Feature Failures

When a utility such as Window Layout or Dock Preview shows no effect, the root cause is typically a missing privacy permission. The app polls permission states on launch, but if Accessibility or Screen Recording access is denied, the feature silently fails. The troubleshooting guide lists exact permission checks and recovery steps for each utility.

Functional Bugs and Performance Regressions

Recent releases have addressed several architectural edge cases documented in the CHANGELOG.

App Switcher Freezes and High CPU

Historically, the app switcher queried the Accessibility API for every window on each activation, causing high CPU usage and hangs when encountering slow applications. The recent refactor in Sources/Vorssaint/App/AppDelegate.swift and related switcher modules adds caching for window lists and skips hidden helper windows, resolving the freeze issues noted in CHANGELOG entries #28-30.

Dock Preview Disappearances

Dock thumbnails that revert to app icons or disappear entirely indicate missing Screen Recording permissions, which prevent the app from capturing live window content. This was fixed in version 3.3.5, where the switcher now retries capture after the permission is granted (see CHANGELOG #40-42).

Screen Recording Audio-Video Sync Issues

Earlier versions of the screen recorder suffered from audio and video drift when pausing and resuming captures. The root cause was the separation of audio tracks in the capture pipeline. The code in Sources/Vorssaint/Core/RecorderStrings.swift now synchronizes streams during recording, correcting the alignment issues detailed in CHANGELOG #21-23.

Memory Leaks from Event Listeners

Toggling multiple features on and off could cause high CPU or memory usage because each utility registered its own event listeners without deregistering them when disabled. Recent releases added automatic listener cleanup in the core event handling logic, preventing the leaks described in CHANGELOG #51-55.

Installation and Uninstallation Artifacts

Removing vorssaint-utils sometimes leaves behind settings, login items, or permission grants that affect future reinstalls.

Incomplete Uninstall Leaving Traces

Prior fixes addressed uninstall scripts that failed to remove the launch agent, preferences, or TCC permissions. The current Tools/uninstall.sh script fully removes all traces by deleting the launch agent, preference files, and running tccutil reset for the bundle ID com.vorssaint.utils, as documented in TROUBLESHOOTING sections #67-79.

Diagnostic Commands and Recovery Steps

Run these commands from the repository root to diagnose or resolve the known issues with vorssaint-utils.

Run the built-in self-test to generate a health summary for bug reports:

./build/Vorssaint --selftest

Reset all macOS privacy permissions for the app when permissions "won't stick":

tccutil reset All com.vorssaint.utils

Reset only the Accessibility permission if that specific access is problematic:

tccutil reset Accessibility com.vorssaint.utils

Perform a clean uninstall that removes the app, launch agent, preferences, and permissions:

./Tools/uninstall.sh

Build the app from source to verify code signing and permissions locally:

git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./build.sh
./build.sh --install

Summary

• Gatekeeper warnings occur with unsigned builds; use the right-click Open workaround or build from source via Package.swift.
• Permission-related failures are the most common cause of non-functional features; verify Accessibility and Screen Recording access in System Settings.
• Sticky permissions require resetting the TCC database with tccutil reset when macOS caches old signatures.
• App Switcher freezes were resolved by adding window caching and filtering hidden helpers.
• Screen recording drift was fixed by synchronizing audio-video streams in RecorderStrings.swift.
• Complete uninstallation requires Tools/uninstall.sh to remove launch agents and reset permissions.

Frequently Asked Questions

How do I fix Gatekeeper warnings when opening vorssaint-utils?

When macOS displays a security warning preventing the app from opening, right-click the application bundle and select Open to bypass the code signature check. For permanent resolution, build the signed bundle from source using ./build.sh, which creates a properly notarized binary recognized by Package.swift configuration.

Why does a specific utility work intermittently or not at all?

Intermittent functionality almost always indicates missing or unstable privacy permissions. Check that vorssaint-utils has been granted Accessibility, Screen Recording, and System Audio Recording permissions in System Settings. If the permission state appears stuck, reset it entirely using tccutil reset All com.vorssaint.utils and re-grant access.

How do I completely remove vorssaint-utils and reset all permissions?

Run the comprehensive uninstall script located at Tools/uninstall.sh, which removes the application, its launch agent, preference files, and resets all TCC permissions via tccutil reset. This ensures no cached permissions or settings persist that could interfere with future installations.

What should I do if the App Switcher freezes or misses windows?

Ensure you are running version 3.3.5 or later, which includes a refactor of the window querying logic in Sources/Vorssaint/App/AppDelegate.swift to cache results and skip hidden helper windows. If issues persist, check Accessibility permissions and run ./build/Vorssaint --selftest to verify the window enumeration health.

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