TiltSwitch is a lightweight macOS menu bar app that uses the front camera and Apple Vision to detect head roll. Tilting your head switches Mission Control spaces:
- Tilt right:
Control+Right Arrow - Tilt left:
Control+Left Arrow
It is built with pure Apple frameworks, no third-party dependencies, and a programmatic AppKit entry point.
- Dock icon plus visible
TiltSwitchmenu bar status item - Floating control panel that opens at launch and stays available from the Dock icon
- Real-time head roll detection with
AVCaptureSessionandVNDetectFaceLandmarksRequest - Mission Control space switching through
CGEvent - 800ms cooldown to avoid repeated space switches
- Menu bar item briefly changes to
LeftorRightwhen a tilt is detected - Sensitivity presets:
- Low:
0.25radians - Medium:
0.35radians - High:
0.5radians
- Low:
- Transparent floating HUD with left/right SF Symbols
- Diagnostics menu for self-checks, HUD tests, and Mission Control switch tests
- Camera starts only while TiltSwitch is enabled
- Camera session is released when disabled, sleeping, locked, or quitting
- No network calls, telemetry, analytics, storyboard, XIB, packages, or external dependencies
- macOS 13.0 or newer
- Xcode with macOS SDK
- Front-facing camera
- Mission Control keyboard shortcuts enabled for
Control+ arrow keys
The latest packaged build is available from GitHub Releases:
TiltSwitch-vX.Y.Z-macOS.dmg- drag-and-drop installerTiltSwitch-vX.Y.Z-macOS.zip- zipped app bundlechecksums.txt- SHA-256 checksums
Early builds are not notarized. If macOS blocks first launch, right-click TiltSwitch.app, choose Open, then confirm.
Website: https://boblebol.github.io/TiltSwitch/
After launching TiltSwitch, use the floating control panel. You can reopen it from the Dock icon or from the TiltSwitch item in the top-right menu bar, near Control Center:
- Click
Checkin the floating panel, or openDiagnostics > Run Self Check. - Confirm camera permission is OK.
- Click
LeftandRightin the panel, or runDiagnostics > Test HUD LeftandTest HUD Right. - Run
Diagnostics > Test Previous SpaceandTest Next Spacefrom the menu bar when it is visible. - If space switching does not move, open
Mission Control Shortcutsand enableControl+ Left/Right Arrow.
The app also has quick links to the website, GitHub, Camera Settings, and Quit.
If you see the Dock icon but not the menu bar item, make sure you are running 0.1.10 or newer. The floating panel remains usable even when macOS hides extra menu bar items.
Open TiltSwitch.xcodeproj in Xcode and build the TiltSwitch scheme.
Command line:
xcodebuild build \
-project TiltSwitch.xcodeproj \
-scheme TiltSwitch \
-configuration ReleaseRun tests:
xcodebuild test \
-project TiltSwitch.xcodeproj \
-scheme TiltSwitch \
-destination 'platform=macOS'For CI or unsigned local builds, pass CODE_SIGNING_ALLOWED=NO.
TiltSwitch requests camera permission on first launch. The camera usage description is:
TiltSwitch uses the camera to detect head tilt. No video is recorded or transmitted.
The app uses the camera frames locally only for Vision face roll detection.
TiltSwitch intentionally keeps one file per concern:
AppDelegate.swift- status item, menu, settings, permission flow, HUD panel, lifecycleControlPanelView.swift- SwiftUI floating controls and status diagnosticsHeadTiltMonitor.swift- camera capture, Vision face landmarks, 15fps frame throttlingSpaceSwitcher.swift-CGEventposting and cooldown logicHUDView.swift- SwiftUI arrow overlay and fade timing
More details are in docs/ARCHITECTURE.md.
TiltSwitch does not record, store, transmit, upload, log, or analyze video outside the local process. See docs/PRIVACY.md.
AI agents and contributors should start with AGENTS.md and docs/AI_CONTEXT.md. These files summarize the project constraints, architecture, and verification commands.
MIT. See LICENSE.