Voice assistant that actually gets things done. Press a hotkey, speak, and Nudge handles the rest — tasks, alarms, notes, clipboard, links.
Built on Hive, a local-first agent framework. Open source. Bring your own LLM.
You speak → STT transcribes → Intent classified → Agent acts → Done
# "Remind me to call mom tomorrow"
→ STT: "remind me to call mom tomorrow" (Groq Whisper, 340ms)
→ Intent: alarm (92%) (120ms)
→ Agent: set_alarm("Call mom", 24h) (280ms)
✓ Total: 740mspip install nudge-ai
nudge setupnudge # Start — press hotkey to record
nudge test # Quick 2s recording test
nudge preset fast # Switch to Groq free tier (200ms responses)- Voice-first — Hotkey to record, release to process
- Tasks & Alarms — Create todos, set reminders naturally
- Knowledge Base — Save and recall notes with semantic search
- Clipboard & Links — Copy results, save URLs by voice
- Soul System — Personalize behavior via
~/.nudge/soul.md - Provider Flexibility — Groq, OpenAI, Anthropic, Ollama, LM Studio
- Presets —
fast(free cloud),offline(local),default(balanced) - Pipeline Timing — See exactly how long each stage takes
| Preset | STT | LLM | Latency | Cost |
|---|---|---|---|---|
fast |
Groq Whisper | Groq (lite) | ~200ms | Free |
default |
Groq Whisper | Groq (standard) | ~500ms | Free |
offline |
Local Whisper | Ollama | ~2s | $0 |
Nudge reads ~/.nudge/soul.md to understand how you work:
nudge soul edit # Open in your editor
nudge soul show # Display current soulExample:
## Who You Are
name: Alex
timezone: America/New_York
## How You Work
- "Later" means this evening
- High priority = today, Medium = this week
- Keep task descriptions short| Command | Description |
|---|---|
nudge |
Start voice assistant (hotkey mode) |
nudge setup |
Interactive setup wizard |
nudge test |
2s recording test |
nudge config |
Show configuration |
nudge preset NAME |
Load preset (default/fast/offline) |
nudge serve |
Start HTTP server |
nudge history |
Recent interactions |
nudge soul show |
Display soul.md |
nudge soul edit |
Edit soul.md |
The app ships as a standalone menu-bar + windowed app. The distributed Nudge.app
bundles the Python backend, so end users need no pip install — it auto-starts
the bundled nudge serve on launch. Installing the CLI is only needed for the
nudge terminal command, or as a runtime fallback for a BUNDLE_BACKEND=0 dev build:
pipx install nudge-ai # optional — CLI only; the distributed app is self-containedmake icon # generate packages/widget/Nudge.icns from the source PNG
make app # build dist/Nudge.app (ad-hoc signed)
make dmg # build dist/Nudge-0.2.0.dmg
make signing-cert # optional, run once: stable self-signed identitymake icon reads packages/widget/icon-source/Nudge.png, or pass a path:
packages/widget/scripts/make-icon.sh /path/to/logo.png.
make signing-cert creates a self-signed "Nudge Dev" code-signing identity in
your login keychain so the microphone permission survives rebuilds (otherwise
each make app re-prompts). It is not notarization — the Gatekeeper step below
still applies.
- Left-click the menu-bar icon → open the dashboard popover.
- Right-click (or Control-click) the icon → menu with Open, Restart Backend, Launch at Login, and Quit Nudge.
- The same actions live in the dashboard's Settings tab.
The app auto-starts nudge serve on launch and stops the server it started when
you quit.
Drag Nudge.app from the DMG into Applications. Because the app isn't notarized yet, Gatekeeper blocks the first launch:
- macOS 15+ (Sequoia): double-click once (it's blocked), then System Settings → Privacy & Security → Open Anyway. Right-click → Open no longer bypasses Gatekeeper on these versions.
- macOS 13–14: right-click (Control-click) Nudge.app → Open → Open.
- Any version, fast path:
xattr -dr com.apple.quarantine /Applications/Nudge.app
After this once, it launches normally. On the first voice command, macOS asks for microphone permission — click Allow.
Full build / signing / hosting / install details (and the notarization path) live in docs/distribution.md.
Nudge ships an MCP server so your coding agent (Claude Code, Codex, Cursor) can drop tasks, reminders, notes, and links into Nudge without leaving the editor. The easiest way: open the app → Configure → Connect Nudge to your coding IDE → Copy prompt, then paste it into your agent — it wires up the MCP and capture behavior for you. The MCP server writes straight to your local Nudge store, so the app/backend doesn't need to be running for capture. See docs/mcp.md for manual setup and details.
nudge/
├── packages/
│ ├── core/ # Python: voice engine + CLI
│ ├── web/ # Next.js: landing page + dashboard
│ └── api/ # FastAPI: hosted backend
├── docs/
└── README.md
cd packages/core
uv venv && source .venv/bin/activate
uv pip install -e ".[dev,server]"
make test
make lintMIT