Shoo

A macOS menu-bar app that watches you through the webcam and gently tells you to stop when you bring your hands to your face — nail-biting, nose-poking, and other unconscious habits.

All image processing happens on-device using Apple's Vision framework. No video, frames, or data ever leave your Mac.

How it works

Camera (AVCaptureSession)
   → CameraController        downscales each frame into an owned buffer on the session queue
   → HandFaceDetector        Vision: face landmarks + hand pose (21 landmarks)
   → ProximityAnalyzer       pure logic: fingertip proximity to mouth/nose regions
   → GestureDetector         temporal smoothing + hysteresis → DetectionResult
   → AlertManager            state machine: debounce + cooldown + escalation
   → OverlayController        centered "Seen it!" overlay, auto-dismisses

The menu-bar UI lets you enable/disable watching, tune sensitivity and cooldown, and launch at login.

See docs/ARCHITECTURE.md and docs/PRIVACY.md for details.

Website: https://jkkronk.github.io/shoo/ — the privacy policy and support page are hosted there (source in site/).

Requirements

• macOS 14.0 or later
• Xcode 26 or later (CI builds with Xcode 26.6; the committed project uses objectVersion = 77)
• A built-in or external webcam

Download

Get Shoo free on the Mac App Store (listed as Shoo: Hands Off Your Face). That's the easiest way: it's signed, reviewed by Apple, and updates automatically.

Unsigned GitHub build

Prefer not to use the App Store? Grab the latest zipped .app from the Releases page, unzip it, and move Shoo.app to /Applications. Install either this or the App Store version, not both (they share a bundle ID).

This build is not notarized. It runs on-device inside the same macOS sandbox (the app's only entitlement is camera access), but Gatekeeper will block the first launch. To open it:

• Click Done in the dialog, then open System Settings → Privacy & Security, scroll to Security, and click Open Anyway next to the message about Shoo. Launch again and confirm, or

• clear the quarantine flag in Terminal and it launches without any dialog:

  xattr -dr com.apple.quarantine /Applications/Shoo.app

On macOS 14 and earlier, right-click Shoo.app → Open → Open also works.

Prefer to build it yourself? See Build & run below.

Build & run

The Xcode project is committed, so the simplest path is:

open Shoo.xcodeproj

Then select the Shoo scheme and run (⌘R).

Alternatively, regenerate the project from its spec (project.yml) with XcodeGen:

bash scripts/bootstrap.sh   # installs xcodegen if needed, then `xcodegen generate`

Command-line build and test:

xcodebuild -project Shoo.xcodeproj -scheme Shoo build
xcodebuild -project Shoo.xcodeproj -scheme Shoo test

On first run, macOS will ask for camera permission — this is expected and required for the app to function.

Project layout

Shoo/            App, Camera, Detection, Alerting, Views, Models, Support
ShooTests/       Unit tests for the pure detection logic
project.yml      XcodeGen spec (source of truth for the Xcode project)
scripts/         bootstrap / tooling
docs/            Architecture & privacy notes
site/            Static marketing site, privacy policy & support page (GitHub Pages)

Roadmap

• Real hand-to-face detection (face landmarks + hand pose, mouth/nose regions)
• False-positive mitigation (chin-rest penalty, temporal hysteresis)
• App icon & menu-bar glyph

Open issues and improvements are tracked in docs/AUDIT.md.

Privacy

Shoo is camera-only and offline by design. It never records, stores, or transmits imagery. See the hosted privacy policy or docs/PRIVACY.md.

License

Shoo is released under the MIT License.