Head tracking display switcher for macOS

gazectl uses your webcam to detect which monitor you're looking at and automatically switches focus to it. It uses Apple's Vision framework for real-time face tracking and native macOS APIs to switch monitor focus — no third-party window manager required.

macOS only. Requires macOS 14+.

Permissions

gazectl needs two macOS permissions to work:

• Camera — for head tracking via the webcam
• Accessibility — for moving the cursor and clicking to switch monitor focus

Grant both in System Settings → Privacy & Security. macOS will prompt you on first run.

Install

npx gazectl@latest

Or install globally:

npm i -g gazectl

Usage

# First run — calibrates automatically
gazectl

# Force recalibration
gazectl --calibrate

# With verbose logging
gazectl --verbose

On first run, gazectl asks you to look at each monitor and press Enter. It samples your head angle for 2 seconds per monitor, then saves calibration to ~/.local/share/gazectl/calibration.json.

Options

| Flag | Default | Description | |------|---------|-------------| | --calibrate | off | Force recalibration | | --calibration-file | ~/.local/share/gazectl/calibration.json | Custom calibration path | | --camera | 0 | Camera index | | --verbose | off | Print yaw angle continuously |

How it works

1. Calibrate — look at each monitor, gazectl records the yaw angle
2. Track — Apple Vision detects head yaw in real-time (~30fps)
3. Switch — when yaw crosses the midpoint between calibrated angles, moves the cursor to the target monitor and clicks to focus

Build from source

swift build -c release
cp .build/release/gazectl /usr/local/bin/gazectl