Airhands

Airhands is a native macOS menu bar utility that uses the webcam plus on-device Vision hand tracking to control the cursor without touching the keyboard or trackpad.

Current Focus

• Manual Start Control / Stop Control
• Cursor movement from index fingertip motion
• Pinch to click
• Pinch and hold to drag
• Calibration is optional for first testing

How To Run

1. Open Airhands.xcodeproj in Xcode.
2. Select the Airhands scheme.
3. Run on My Mac.
4. Grant Camera and Accessibility permissions when prompted.
5. Open Calibration & Debug from the menu bar if it does not auto-open.
6. Click Start Control.

How To Test Cursor Control

1. Keep one full hand visible in the white box.
2. Move your index fingertip to steer the cursor.
3. Quick thumb-index pinch to click.
4. Hold the pinch to drag.

If the cursor feels off, try these first:

• Move your hand farther from the camera so the whole hand fits in frame.
• Use the default white interaction box before calibrating.
• Recalibrate only after basic cursor motion feels stable.

Calibration

Calibration now uses two visible targets:

• Blue target: capture top-left reach
• White target: capture bottom-right reach

If the captured points are too close together, Airhands will reject the save and show an error instead of failing silently.

Project Layout

• Airhands/Services: camera, tracking, permissions, cursor events
• Airhands/GestureEngine.swift: gesture-to-intent reducer
• Airhands/AppModel.swift: app coordinator and runtime state
• Airhands/Views: menu bar, onboarding, calibration, settings
• AirhandsTests: reducer and fixture tests

Build

xcodebuild -project Airhands.xcodeproj -scheme Airhands -destination 'platform=macOS' build

Test

xcodebuild -project Airhands.xcodeproj -scheme Airhands -destination 'platform=macOS' test