eyeswitch

Look at a screen. It gets focus.

eyeswitch uses your webcam and TensorFlow.js to track where your head is pointing, then automatically moves macOS focus to whichever monitor you're looking at — no keyboard shortcut, no clicking, no magic.

---

Requirements

• macOS (uses CoreGraphics + Accessibility APIs)
• Node.js ≥ 18
• Xcode Command Line Tools — xcode-select --install
• A webcam

---

Installation

npm install -g eyeswitch

The native helper binary compiles automatically on install. If it fails:

npm run build:helper

Grant two permissions (one-time):

Permission	Where
Camera	System Settings → Privacy & Security → Camera
Accessibility	System Settings → Privacy & Security → Accessibility → enable your terminal app

---

Quick start

eyeswitch doctor      # check everything is set up
eyeswitch calibrate   # look at each monitor when prompted
eyeswitch             # start tracking

Press p to pause/resume. Ctrl+C to stop.

---

Commands

eyeswitch — start tracking

Options:
  --sensitivity <level>    Preset: low | medium | high
  --no-click               Warp cursor only, no synthetic click
  --dry-run                Log gaze without switching focus
  --verbose                Print yaw/pitch values on every frame
  --camera <index>         Camera index (default: 0)
  --calibration-file <path>  Custom path to calibration JSON
  --calibrate              Force recalibration on startup

eyeswitch calibrate

Look at each screen and press Enter — eyeswitch samples your gaze for ~8 seconds per monitor and saves the result.

eyeswitch calibrate               # calibrate all monitors
eyeswitch calibrate --monitor 2   # recalibrate only monitor 2 (1-based)

eyeswitch doctor

Checks the native helper, camera, accessibility permission, calibration data, and TF.js model:

  ✓  Native helper binary
  ✓  Accessibility permission
  ✓  Camera access
  ✓  Calibration data          2 monitors calibrated
  ✓  TF.js model

eyeswitch config get [key]

Print the current config (or a single value).

eyeswitch config get
eyeswitch config get smoothingFactor

eyeswitch config set <key> <value>

Persist a config value to ~/.config/eyeswitch/config.json.

eyeswitch config set smoothingFactor 0.4
eyeswitch config set switchCooldownMs 300

eyeswitch status

Show whether eyeswitch is calibrated and which monitor is currently focused.

eyeswitch reset

Delete saved calibration data.

eyeswitch calibration export

Export calibration data to stdout or a file.

eyeswitch calibration export > ~/cal-backup.json
eyeswitch calibration export -o ~/cal-backup.json

eyeswitch calibration import <file>

Import calibration from a JSON file.

eyeswitch calibration import ~/cal-backup.json

---

Configuration

All values live in ~/.config/eyeswitch/config.json. Edit with eyeswitch config set or directly.

Key	Default	Description
smoothingFactor	0.3	EMA smoothing — 0 = raw, closer to 1 = very smooth
switchCooldownMs	500	Minimum ms between focus switches
hysteresisFactor	0.25	Bias toward staying on the current monitor (0–1)
minFaceConfidence	0.4	Minimum detection confidence to process a frame
cameraIndex	0	Which webcam to use
targetFps	30	Frame capture rate
verticalSwitching	false	Enable pitch-based switching for top/bottom monitor layouts

Sensitivity presets

Preset	smoothingFactor	hysteresisFactor	switchCooldownMs
low	0.5	0.40	800 ms
medium	0.3	0.25	500 ms (default)
high	0.1	0.10	200 ms

eyeswitch --sensitivity high   # snappier switching
eyeswitch --sensitivity low    # more stable, fewer accidental switches

---

Troubleshooting

Problem	Fix
Focus doesn't switch	Check Accessibility permission — eyeswitch doctor
Camera not found	Try --camera 1 if you have multiple webcams
Switching feels jittery	Use --sensitivity low or eyeswitch config set switchCooldownMs 800
Slow to detect face	Lower minFaceConfidence — eyeswitch config set minFaceConfidence 0.3
npm run build:helper fails	Run xcode-select --install first
"Native helper not available"	Run npm run build:helper manually
Wrong monitor gets focus	Recalibrate — eyeswitch calibrate

---

How it works

1. Your webcam captures frames via node-webcam
2. TensorFlow.js + MediaPipe FaceMesh extracts 468 3D facial landmarks per frame
3. Yaw and pitch are computed from jaw-outline and nose-tip landmarks (works with glasses)
4. An EMA filter smooths the pose to cut down on jitter
5. A calibration map translates gaze angles to the nearest monitor using Euclidean distance with hysteresis
6. The native ObjC helper (eyeswitch-helper) uses CoreGraphics to warp the cursor and the Accessibility API to fire a synthetic click

---

Platform support

Platform	Status
macOS	Full support
Linux	Not supported (native helper is macOS-only)
Windows	Not supported

---

Development

git clone https://github.com/Abhijitam01/eyeswitch.git
cd eyeswitch
npm install
npm run build
npm test

To iterate on the native ObjC helper:

npm run build:helper

Project structure

src/
  index.ts                  CLI entry point (Commander.js)
  cli.ts                    Output helpers (chalk, ora)
  config.ts                 Config schema, load/save, sensitivity presets
  types.ts                  Shared TypeScript interfaces
  camera/
    frame-capture.ts        Webcam → FrameBuffer
  face/
    face-detector.ts        TF.js MediaPipe FaceMesh wrapper
    pose-estimator.ts       Landmarks → yaw/pitch with EMA smoothing
  calibration/
    calibration-manager.ts  Sample collection, persistence, gaze→monitor mapping
    sample-aggregator.ts    Immutable median aggregator for calibration samples
  monitor/
    focus-switcher.ts       Calls native helper to switch focus
    monitor-detector.ts     Queries monitor layout via native helper
    monitor-mapper.ts       Maps gaze to MonitorLayout using calibration data
  native/
    native-bridge.ts        Cross-platform TypeScript wrapper for the native helper
    helper/
      eyeswitch-helper.m    macOS native helper (CoreGraphics, Accessibility)
      eyeswitch-helper-win.c  Windows native helper (Win32 user32/gdi32)

---

Built by Abhijitam01