██████╗  █████╗ ███████╗███████╗ ██████╗████████╗██╗
██╔════╝ ██╔══██╗╚══███╔╝██╔════╝██╔════╝╚══██╔══╝██║
██║  ███╗███████║  ███╔╝ █████╗  ██║        ██║   ██║
██║   ██║██╔══██║ ███╔╝  ██╔══╝  ██║        ██║   ██║
     ╚██████╔╝██║  ██║███████╗███████╗╚██████╗   ██║   ███████╗
      ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝ ╚═════╝   ╚═╝   ╚══════╝

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

Star History