How to Configure Per-App Rules for Vorssaint's Window Switcher

You can configure per-app rules for Vorssaint's window switcher through the Settings UI under Switcher > Per-App Rules or by directly modifying the switcherAppRules dictionary in UserDefaults to set application-specific behaviors.

Vorssaint Utils is an open-source macOS utility suite that provides advanced window management capabilities. The window switcher component supports granular per-app rules that determine whether applications appear in the switcher, display as window-only entries, or remain hidden entirely. This configuration is managed through both a graphical interface and the underlying Swift implementation in vorssaint/vorssaint-utils.

Configuring Rules via the Settings UI

Opening the Per-App Rules Panel

Navigate to the Vorssaint Settings window by clicking the gear icon in the menu bar or selecting Vorssaint → Preferences. In the settings sidebar, select Switcher, then scroll to the Per-App Rules section at the bottom of the pane. This interface is backed by Sources/Vorssaint/UI/Settings/SwitcherAppRulesList.swift.

Adding and Modifying Rules

Click the + button to create a new rule entry. Enter the target application's bundle identifier (for example, com.apple.Safari) in the identifier field. From the behavior dropdown, select one of three modes:

• Include – The application appears normally in the switcher (default behavior when no rule exists).
• Window-only – The app icon is omitted; only its individual windows appear in the switcher list.
• Hide – The application and all its windows are completely excluded from the switcher.

Changes are written immediately to UserDefaults under the key switcherAppRules and take effect without requiring an application restart.

Understanding the Implementation Layer

The runtime logic that enforces these rules resides in Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift. This service reads the rule dictionary during switcher construction to filter the visible application set.

The following example demonstrates the JSON structure stored in UserDefaults:

// Example of the JSON that backs the per‑app rules (stored in user defaults)
let exampleRules = [
    "com.apple.Safari": "include",   // default – appears normally
    "com.apple.mail": "windowOnly", // only its windows are shown
    "com.microsoft.Word": "hide"    // completely omitted from the switcher
]
UserDefaults.standard.set(exampleRules, forKey: "switcherAppRules")

The SwitcherSupport class interprets these values using logic similar to the implementation below. The shouldShowApp(_ bundleID: String) method returns a Boolean indicating whether the app should participate in the switcher:

// How SwitcherSupport interprets a rule
func shouldShowApp(_ bundleID: String) -> Bool {
    guard let rule = UserDefaults.standard.dictionary(forKey: "switcherAppRules")?[bundleID] as? String
    else { return true }                // no rule → include
    return rule != "hide"               // hide → false, others → true
}

Key Source Files

• Sources/Vorssaint/UI/Settings/SwitcherAppRulesList.swift – Defines the user interface for viewing and editing the per-app rule list.
• Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift – Contains the core service that reads switcherAppRules and determines switcher visibility at runtime.
• README.md – Provides high-level documentation on switcher features, including the per-app rules system.

Summary

• Access per-app rule configuration via Settings > Switcher > Per-App Rules.
• Choose from three behaviors: include (default), windowOnly, or hide.
• Rules persist in UserDefaults under the key switcherAppRules as a dictionary mapping bundle IDs to behavior strings.
• SwitcherSupport.swift evaluates these rules dynamically; changes apply instantly without restarting Vorssaint.
• The UI layer in SwitcherAppRulesList.swift provides a visual editor for the underlying data store.

Frequently Asked Questions

Where does Vorssaint store per-app switcher rules?

Vorssaint stores these rules in the standard UserDefaults system under the key switcherAppRules. According to the vorssaint/vorssaint-utils source code, this dictionary maps bundle identifiers (such as com.apple.Safari) to behavior strings (include, windowOnly, or hide).

What happens if I don't set a rule for a specific app?

If no entry exists in the switcherAppRules dictionary for a given bundle ID, the SwitcherSupport service defaults to the include behavior. This means the application appears normally in the window switcher alongside all other running apps.

How do I hide an app completely from the window switcher?

Set the app's rule value to "hide" either through the Settings UI by selecting Hide from the behavior dropdown, or programmatically by updating the UserDefaults dictionary. When the rule equals "hide", the shouldShowApp method returns false, excluding the app from the switcher interface entirely.

Can I edit per-app rules without opening the Settings UI?

Yes, you can modify the rules programmatically using Swift's UserDefaults API or the defaults command-line tool. Write a dictionary to the switcherAppRules key containing the desired bundle identifiers and behavior strings; the switcher will read these values on its next update cycle.

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