Settings reference
Open Settings from the menu bar, or press Command + comma while HyperSwitcher is active. Most behavior belongs to the active profile; license, login, Dock, onboarding, command-line installation, and telemetry are shared.
General
Section titled “General”| Setting | What it controls |
|---|---|
| Hyper key authority | Whether HyperSwitcher or an external app maps the physical Hyper key. |
| Physical key | Caps Lock or Right Command for the built-in Hyper key. |
| App shortcuts include Shift key | Uses Command + Control + Option + Shift instead of the default three-modifier layer. This leaves saved second-layer assignments inactive. |
| Enable second shortcut layer | Lets recorders use physical Left Shift for a second set of shortcuts when HyperSwitcher owns Hyper and the base layer excludes Shift. Turning it off preserves those assignments as dormant conflicts. |
| Open HyperSwitcher at login | Registers or removes the macOS login item. |
| Show HyperSwitcher in Dock | Shows a Dock icon without changing the menu bar item. |
| Send anonymous telemetry | Enables or disables anonymous daily usage totals, setting choices, and rare milestones. |
| App switching | Chooses Follow pointer or Last used when entering another app. |
| Window switching | Chooses Follow pointer or Cycle all windows (the default) for repeat presses. |
| Temporary shortcuts | Captures the focused app or the exact focused window. |
| Flash focused window | Briefly outlines the window HyperSwitcher selected. |
| Move reopened windows to pointer display | Moves a newly reopened window before focusing it. |
Apps settings contains licensed Shortcut Groups, a searchable installed-app list, and All / Assigned / Conflicts / Unavailable filters.
Open an app to record or reset its shortcut, choose whether to include minimized windows while cycling, and copy its focus URL or Terminal command. Record without Shift for the base layer or with only physical Left Shift for the optional second layer. The recorder rejects Right Shift and both Shift keys.
Finder’s detail page has Destination shortcuts for adding folders with an optional custom name and their own Hyper key.
Shortcuts
Section titled “Shortcuts”| Setting | What it controls |
|---|---|
| Back | Returns to the previously focused available window from the current HyperSwitcher session. |
| Forward | Moves forward through the session’s window history after using Back. |
| Cycle app windows | Cycles through windows of whichever app is focused. |
| Cycle workspace windows | Cycles available members of the current Workspace in visual slot order. |
All four recorders start empty and belong to the active profile. Each can use the base or optional second layer. The Workspace recorder is disabled with an explanation while Workspaces are off or a license is unavailable.
Layout
Section titled “Layout”| Setting | What it controls |
|---|---|
| Enable Layouts | Registers Quick Layout, Workspaces, and Tidy Up. App and Finder destination shortcuts still work when off, and a custom Layout action key is released for app, destination, group, and cycle shortcuts. |
| Enable Vim navigation keys | Uses H, J, K, and L for layout movement and marks colliding shortcuts as conflicts. A custom Layout action key on one of those letters keeps the action-key behavior. |
| Layout action key | Holds either Shift by default, or only physical Right Shift while the second shortcut layer is available, to maximize or restore a window and combine regions. A recorded custom key replaces Shift; an occupied key is saved with a shortcut conflict warning. |
| Quick Layout appearance | Shows the full overlay or compact preview. The Workspace editor always stays compact. |
| Resize grid | Sets window, selected-region, and Workspace-slot resize steps to Coarse (8 × 8), Standard (16 × 16, the default), or Fine (24 × 24). |
| Window edge behavior | Controls how edge contact changes window resizing: Ignore edges (the default), Resize both dimensions, or Adapt to edges. |
| Layout gaps | Sets spacing around placed windows. |
| Show Quick Layout after | Sets the hold time before the overlay appears; instant controls still act immediately. |
| Animate window placement | Smoothly moves and resizes windows for Quick Layout, Workspace resizing, and showing a Workspace. On by default; macOS Reduce Motion overrides it. |
| Animation duration | Sets the animation from 100 to 500 ms. The default is 200 ms. |
| Enable Workspaces | Keeps one live multi-window Workspace per display and Space for this app session. Requires a license. |
| While filling a Workspace | Focuses the next unplaced window, keeps the placed window focused, or assigns newly focused windows to empty slots. |
The Tidy Up section independently enables: Fix common layouts, Bring windows on screen, Fit oversized windows, Clear tiny overlaps, Even out split gaps, Align nearby edges, and Clear outer screen gaps.
Automation
Section titled “Automation”| Setting or action | What it does |
|---|---|
| Create an action | Chooses an action and its options. Only Focus app requires an app selection; window, Workspace, and temporary-shortcut actions use the focused external context. |
| Generated output | Copies the correctly encoded URL action or equivalent Terminal command without running it. |
| Command Line | Shows the current installation state and installs or repairs the user-level command in ~/.local/bin. |
The generator covers actions that have both URL and CLI forms. CLI-only status, list, and development regression commands are documented separately in the Automation guide.
License, Permissions, and Feedback
Section titled “License, Permissions, and Feedback”- License buys or activates a key, shows its status, deactivates this device, or removes the local record.
- Permissions shows Accessibility status and links to the correct macOS Privacy & Security pane.
- Feedback sends a message with an optional reply email and individually removable anonymous details.
Advanced
Section titled “Advanced”| Setting or action | What it does |
|---|---|
| Precise window focusing | Uses HyperSwitcher’s single-window focus method. Turn it off for the simpler macOS path on restricted Macs. |
| Experimental Shortcut Replay | Adds replay controls for recording or testing scripted demo scenarios in this profile. |
| Reveal in Finder | Opens the active settings file. |
| Validate File | Checks whether the file can be read. |
| Reload | Reads the file again and rebuilds shortcuts. |
| Diagnostic Logs → Export… | Saves a redacted local diagnostic report. |
| Restart Onboarding | Returns Settings to the guided setup flow. |
| Reset Defaults | Removes the current configuration and returns to defaults. Back up first. |
Experimental Shortcut Replay synthesizes keyboard input for demos and tests. For exact keys and gestures, see the keyboard shortcut reference.