SpineSpy

AI-powered posture & focus monitor that runs in your macOS menubar. Takes periodic snapshots to detect bad posture and phone distractions without keeping your camera always on.

If you want tiny local-first tools for healthier desk work, starring helps me know this is worth polishing.

Demo

The demo shows the floating pet changing state and playing a reminder after repeated bad snapshots.

Privacy

SpineSpy processes snapshots locally on your device. Camera frames stay in memory and are not uploaded or stored unless you explicitly choose Save Snapshot. Monitoring performs no network requests. Source builds download the two checksum-verified model files only when you run ./scripts/download_models.sh.

Features

• Checks posture without a camera always-on feeling - Opens the webcam briefly, analyzes a snapshot, then closes it
• Learns your normal sitting position - Calibrates against your own good-posture baseline instead of using a one-size-fits-all angle
• Catches both slouching and leaning - Flags forward slouching and side tilt with MediaPipe Pose
• Nudges you when attention drifts - Spots phone distractions with a lightweight MediaPipe object detector
• Smart alerts - Shows a notification and plays a posture reminder clip after repeated bad posture
• Easy to keep out of the way - Runs from the macOS menubar with a floating posture pet and speech bubble, pause, interval, calibration, and sound toggles
• Keeps camera choice predictable - Defaults to the Mac's built-in camera and lets you explicitly choose another connected camera
• Makes camera use visible - Shows the selected camera plus opening, capturing, off, and local-processing states in the menubar
• Makes every capture predictable - Shows the exact local time of the next scheduled capture and stops scheduling while paused
• Remembers your preferences - Persists the camera, interval, sound setting, and calibration between launches

Setup

# Clone the repo
git clone https://github.com/jananadiw/spinespy.git
cd spinespy

# Install dependencies
poetry install

# Download and checksum-verify the local AI models
./scripts/download_models.sh

Usage

# Option 1: Using the run script
./run.sh

# Option 2: Poetry script
poetry run start

# Option 3: Direct Python module
poetry run python menubar_app.py

Build

poetry install --with dev
./build_dmg.sh

The reproducible macOS build requires a native Apple Silicon host, Python 3.11, Poetry 2.3.1, create-dmg 1.3.0, and the verified local model assets pose_landmarker.task and efficientdet_lite0.tflite. It targets macOS 15, outputs dist/SpineSpy.app and SpineSpy.dmg, and fails if bundle policy checks fail or the compressed DMG exceeds 200 MB.

Development builds use an ad hoc signature and are not notarized. Official releases are signed, notarized, and staged by GitHub Actions after a version bump reaches main, then published after clean-Mac validation; see docs/releasing.md.

The app appears as a 🦸 icon in your menubar and shows a small floating posture pet with a state message above your windows. Right-click the menubar icon to:

• Pause Monitoring / Resume Monitoring - Stop or restart scheduled captures in one click
• Next capture: ... - See the exact local time of the next scheduled capture, or confirm that monitoring is paused
• Camera: ... - See exactly when the camera is opening, capturing, off, or processing locally
• Interval - Change snapshot frequency
• Settings → Camera - Choose a connected camera; changing cameras requires recalibration
• Settings → Sound Clips - Turn posture reminder clips on/off
• Calibrate - Capture your current good-posture baseline
• Quit - Exit the app

How It Works

1. Every N minutes, the app briefly opens your camera and takes a snapshot
2. MediaPipe Pose analyzes the image for slouching or tilting relative to your calibrated baseline
3. A lightweight MediaPipe EfficientDet-Lite0 model checks for phones in the frame
4. Camera closes immediately after capture; analysis continues locally with the camera off
5. Floating pet artwork, speech bubble, and menubar icon update: upright pet/🦸 (good) or curled pet/🧟 (bad posture)
6. After 5 consecutive bad snapshots → shows a notification and plays a random reminder clip if sound clips are enabled

Configuration

Camera choice, interval, sound, and calibration are saved locally in ~/Library/Application Support/SpineSpy/settings.json. No settings are synced or uploaded.

Detection defaults remain in menubar_app.py:

SLOUCH_THRESHOLD = 0.1   # forward lean sensitivity
TILT_THRESHOLD = 0.05    # side tilt sensitivity
BAD_STREAK_LIMIT = 5     # bad snapshots before alert

Tech Stack

• OpenCV - Camera snapshot capture
• MediaPipe - Real-time pose estimation
• MediaPipe Object Detector - Lightweight on-device phone detection
• rumps - macOS menubar application framework

Requirements

The official v1.2.5 DMG requires:

• An Apple Silicon Mac
• macOS 15 or newer
• A camera

Source execution supports Python 3.10 through 3.12. Reproducible release builds use native arm64 Python 3.11.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• MediaPipe for their excellent pose detection framework
• Google AI Edge for the MediaPipe pose and object-detection models
• The rumps library for making macOS menubar apps easy