Application-Specific Policy Rules

OpenClip allows configuring application-specific behavior rules through AppRule and RuleEngine. App rules control how OpenClip retrieves text and delivers it (paste vs copy) when specific target macOS applications are active.

JSON Configuration Format (rules.json)#

Rules are stored in JSON configuration files (such as ~/.openclip/rules.json) conforming to RuleEngineConfig:

{
  "rules": [
    {
      "bundle-identifiers": ["com.example.game"],
      "disabled": true
    },
    {
      "bundle-identifiers": ["com.example.editor"],
      "hotkey-only": true
    },
    {
      "bundle-identifiers": ["com.example.terminal"],
      "deny-paste": true,
      "retrieval-mode": "menu-copy"
    },
    {
      "bundle-identifiers": ["com.example.app"],
      "gate": {
        "skipRoles": [],
        "allowedCursors": ["beam", "arrow", "pointingHand", "unknown"]
      }
    }
  ]
}

Policy Properties Reference#

retrieval-mode values#

These modes match the per-app defaults assigned by the builtin catalog (DefaultAppRules.catalog); a user rule only overrides the keys it sets, so e.g. gate alone leaves retrieval-mode at the app's default.

Identifier Matching & Shortcuts#

Bundle IDs#

Plain entries match the target application's bundle identifier. Apps without one — CLI tools and SDL apps such as scrcpy — are targeted by scoped identifiers:

• "process:scrcpy" matches the process's executable or localized name. Case-insensitive; * wildcards work ("process:scr*").
• "path:/opt/homebrew/bin/scrcpy" matches the executable path; * wildcards work ("path:/opt/tools/*").

The App Rules page and the menu bar's Pause in <App> item write process: rules automatically for bundle-less apps.

Wildcard Pattern Matching#

RuleEngine supports prefix wildcard matching using .* or global wildcard *:

• "com.example.*" matches com.example.app1, com.example.app2, etc.
• "*" matches all applications, including bundle-less ones.

Builtin Group Expansion Aliases#

Rule Evaluation Mechanics#

1. When a selection event is detected, the trigger sites (MacSelectionMonitor, HotkeyManager) query RuleEngine.shared.resolvePolicies(for: appIdentity).
2. RuleEngine matches the target application's identity against effective rules (default rules + user rules): plain patterns against the bundle ID, process: patterns against the process name, path: patterns against the executable path, with .*-prefix / * wildcards.
3. Matched policy settings override default AppPolicyContext values; the resolved retrieval-mode and gate are passed to SelectionRetrievalCoordinator to read the selection.
4. A legacy use-menu-copy: true rule resolves to retrieval-mode: "menu-copy" only when the rule sets no explicit retrieval-mode and no higher-priority builtin retrieval mode applies (the app isn't already assigned a different mode by the builtin catalog).
5. If denyPaste: true is active for the frontmost application, paste delivery is downgraded to copy and the Paste/Cut actions are hidden from the floating popup bar (via the unified PasteAvailability decision).