HyperSwitch

English | 简体中文

A keyboard-first app and window switcher for macOS. Hold a hotkey to browse running apps or windows with live thumbnails, then release to switch — similar in spirit to classic app switchers, rebuilt natively for current macOS.

HyperSwitch is a menu-bar (agent) app: no Dock tile of its own by default, runs in the background, and opens Settings from the menu-bar icon.

Every Settings pane is available in English and Simplified Chinese. Switch the interface language in Settings → General → Language.

	English	简体中文
General — window switcher hotkeys, delay, filters
App Switcher — ⌘ Tab previews and delays
Interaction
Appearance

• Global hotkeys to open an app switcher or window switcher
• Live thumbnails (with Screen Recording) and optional full-size preview
• Search, arrow-key navigation, Return to activate, Escape to cancel
• Space / desktop indicators for off-Space windows
• Configurable delay, thumbnail size, appearance, and interaction options

• General — launch at login, language, presence / menu-bar behaviour
• App Switcher — hotkeys, delay calibration, include filters
• Interaction — keyboard and pointer behaviour while the switcher is open
• Appearance — theme, colours, layout
• About — version and permission status

• macOS 26.0 or later
• Apple Silicon Mac
• Xcode with command-line tools (to build from source)
• XcodeGen (brew install xcodegen locally)

Grant both in System Settings → Privacy & Security. Without Accessibility, HyperSwitch cannot operate.

# Optional but recommended: stable local signing so permissions survive rebuilds
./scripts/setup-signing.sh

# Debug build → /Applications/HyperSwitch.app
./scripts/build.sh

# Release build
CONFIG=Release ./scripts/build.sh

# Always launch via Launch Services
open /Applications/HyperSwitch.app

Important: Do not run the binary from a shell. That inherits the terminal’s TCC grants, so permissions will look granted when they are not.

./scripts/release.sh

Produces dist/HyperSwitch.dmg. With a Developer ID Application certificate and Notary credentials (HyperSwitchNotary profile), the script also signs and notarizes. Otherwise it keeps a local / ad-hoc signature.

Pushes to main run GitHub Actions, which publish the same DMG on Releases. CI builds are typically ad-hoc signed. After downloading a DMG from a browser or AirDrop, clear quarantine if Gatekeeper blocks it:

xattr -d com.apple.quarantine /path/to/HyperSwitch.dmg

Then open the disk image and drag HyperSwitch into Applications.

swift scripts/make-icon.swift /tmp
# copy PNGs into Sources/HyperSwitch/Resources/Assets.xcassets/AppIcon.appiconset/

1. Install and open HyperSwitch.
2. Grant Accessibility (and optionally Screen Recording).
3. Use the configured hotkeys to open the switcher; navigate and release (or press Return) to switch.
4. Open Settings from the menu-bar icon.

hyperswitch/
├── project.yml                 # XcodeGen project definition
├── scripts/
│   ├── build.sh                # Generate project, build, install, sign
│   ├── release.sh              # Release build + DMG (+ optional notarize)
│   ├── setup-signing.sh        # Local self-signed identity for stable TCC
│   ├── make-icon.swift         # Generate iconset
│   ├── extract-strings.py      # Report missing / stale localisation keys
│   └── write-translations.py   # Regenerate Localizable.xcstrings
├── Sources/HyperSwitch/
│   ├── App/                    # Entry, status item, presence
│   ├── Core/                   # Preferences, permissions, localisation
│   ├── Settings/               # Settings panes
│   ├── Switcher/               # Switcher UI, hotkeys, model
│   ├── System/                 # AX, CGS, key codes
│   ├── Thumbnails/             # ScreenCaptureKit thumbnails
│   ├── Windows/                # Window index and actions
│   └── Resources/              # Info.plist, entitlements, assets, strings
└── Tests/HyperSwitchTests/

HyperSwitch.xcodeproj/, .build/, and dist/ are generated and gitignored.

xcodegen generate
./scripts/build.sh
open HyperSwitch.xcodeproj

• App Sandbox is off — required for Accessibility against other apps.
• Signing: build.sh prefers “HyperSwitch Local Signing” from setup-signing.sh, else ad-hoc.
• Swift 6, default actor isolation MainActor, strict concurrency.
• Interface language can follow the system or force English / Simplified Chinese.

scripts/extract-strings.py          # missing / stale keys
scripts/write-translations.py       # rewrite Localizable.xcstrings from the table

1. Quit HyperSwitch from the menu-bar icon.
2. rm -rf /Applications/HyperSwitch.app
3. Optional: defaults delete com.hyperswitch.HyperSwitch 2>/dev/null || true

• HyperDock — hover a Dock icon to preview every open window of that app, including minimized ones and windows on other Spaces, then click through to the one you want.

The two are built the same way — menu-bar agent apps, the same Accessibility / Screen Recording permissions, the same English and Simplified Chinese interface — and they complement each other: HyperSwitch reaches your windows through the keyboard, HyperDock through the Dock with the pointer. Running both is fine; they do not conflict.

This project is licensed under the MIT License.