██████╗ █████╗ ███████╗███████╗ ██████╗████████╗██╗
██╔════╝ ██╔══██╗╚══███╔╝██╔════╝██╔════╝╚══██╔══╝██║
██║ ███╗███████║ ███╔╝ █████╗ ██║ ██║ ██║
██║ ██║██╔══██║ ███╔╝ ██╔══╝ ██║ ██║ ██║
╚██████╔╝██║ ██║███████╗███████╗╚██████╗ ██║ ███████╗
╚═════╝ ╚═╝ ╚═╝╚══════╝╚══════╝ ╚═════╝ ╚═╝ ╚══════╝
**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
```bash
npx gazectl@latest
```
Or install globally:
```bash
npm i -g gazectl
```
## Usage
```bash
# 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
```bash
swift build -c release
cp .build/release/gazectl /usr/local/bin/gazectl
```
# Star History