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

> Learn to configure per-app rules for Vorssaint's window switcher via the Settings UI or by editing UserDefaults for custom application behaviors. Enhance your workflow today.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
// 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:

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift)** – Contains the core service that reads `switcherAppRules` and determines switcher visibility at runtime.
- **[`README.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/SwitcherSupport.swift) evaluates these rules dynamically; changes apply instantly without restarting Vorssaint.
- The UI layer in [`SwitcherAppRulesList.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.