NudgeWhip

A sharp little devil for drifting attention.

NudgeWhip is a privacy-first macOS menu bar companion for serious desktop work.
It catches the moment attention slips, then snaps you back before a short drift becomes a lost hour.

Download

NudgeWhip is distributed through the notarized DMG attached to the GitHub release.

• GitHub Release: v0.4.0
• Asset: NudgeWhip-0.4.0-1.dmg
• Platform: macOS 15 or later

Release Notes · Privacy · Issues · Releases

Why NudgeWhip

Most focus tools drift toward one of two extremes:

• they politely whisper and get ignored
• they escalate into blockers and create friction

NudgeWhip sits in the middle.

It is an attention recall tool: a local intervention layer for people whose work already lives inside demanding Mac workflows. The core idea is simple:

• drifting is normal
• recovery is the moment that matters
• the intervention should be immediate, clear, and local

Release Status

v0.4.0 adds the iOS companion app and CloudKit real-time sync.

Current release lane:

• macOS + iOS companion
• source-first GitHub release
• Free core loop only

Not in scope for v0.4.0:

• Push notifications (CKQuerySubscription + APNs)
• Pet mood system implementation
• StoreKit / Pro packaging
• Recovery Review dashboard
• Schedule presets

What Ships In v0.4.0

• iOS companion app with live CloudKit sync for Mac focus state
• CloudKit real-time pipeline — MacState and RemoteEscalationEvent written to iCloud Private Database on every state change
• Multi-Mac isolation — correctly handles multiple Macs sharing one iCloud account
• Full Korean (한국어) localization for both macOS and iOS
• menu bar app with LSUIElement behavior and no Dock icon
• Accessibility permission onboarding with visible limited-mode fallback
• global idle detection from keyboard and mouse activity
• one-shot idle deadlines instead of noisy polling
• local visual nudges with system notification escalation
• runtime status and countdown in the dropdown
• manual pause controls and schedule controls
• local daily summary stats with trend charts
• settings window and launch-at-login toggle
• CloudKit daily aggregate backup for cross-device data continuity

Onboarding

In The Menu Bar

The little devil lives in the menu bar and steps in when attention starts to slide.

What Makes It Different

Local-first

NudgeWhip is designed around the Mac itself, not around a cloud dashboard. CloudKit is a backup layer, not the source of truth.

Privacy-first

Accessibility permission is used only to detect global input activity. NudgeWhip does not read typed text, capture your screen, inspect browsing history, or collect message content.

Recovery-first

This is not a punishment machine. It is an intervention layer designed to shorten the distance between distraction and return.

Privacy At A Glance

NudgeWhip draws a hard line:

• it uses global input activity only
• it does not inspect typed text or screen contents
• it does not store raw input logs
• it stores summary data locally
• it keeps local app state in SwiftData
• CloudKit sync uses Private Database only — data stays in the user's iCloud

Full disclosure: docs/privacy/accessibility-and-data-disclosure.md

Build And Verify

Requirements:

• macOS 15.0+
• Xcode 17+

Build the app:

xcodebuild build -scheme nudgewhip -destination 'platform=macOS'

Run static analysis:

xcodebuild analyze -scheme nudgewhip -destination 'platform=macOS'

Run unit and runtime tests:

xcodebuild test -scheme nudgewhip -destination 'platform=macOS' -only-testing:nudgewhipTests

Run UI tests:

xcodebuild test -scheme nudgewhip -destination 'platform=macOS' -only-testing:nudgewhipUITests

Note:

• menu bar agent UI tests are more timing-sensitive than standard foreground app UI tests

Technical Shape

Core stack:

• SwiftUI for menu bar, onboarding, and settings UI
• AppKit for global event monitoring and alert/panel coordination
• SwiftData for local persistence
• CloudKit for cross-device state sync (Private Database only)

At a high level:

1. NudgeWhip records the last observed activity timestamp.
2. It schedules a one-shot idle deadline.
3. When the deadline is reached, it starts a local nudge flow.
4. When activity returns, it resets the timer and records local summary data.
5. State changes are written to CloudKit for the iOS companion to read.

Repository Layout

nudgewhip/
├── nudgewhip/              # macOS app source
├── nudgewhipios/           # iOS companion app source
├── nudgewhipTests/         # unit and runtime tests
├── nudgewhipUITests/       # UI tests
└── docs/                   # product, architecture, privacy, QA, and release docs

Documentation Map

• docs/release/v0.4.0.md: v0.4.0 release notes
• docs/release/v0.3.0.md: v0.3.0 release notes
• docs/release/v0.2.0.md: v0.2.0 release notes
• docs/app/v0.3-feature-direction.md: next-version feature direction
• docs/privacy/accessibility-and-data-disclosure.md: permission and data disclosure

Beta Reality

This repository is not a concept dump.

It is an active public-beta / portfolio-stage product:

• the core loop is real
• the app builds and runs
• the release process is documented
• the surface area is still tightening

License

This project is licensed under the MIT License.