stack-nudge

---

 

Supports

Agent	Status
Claude Code	✅
Cursor	✅
Codex	✅
Gemini CLI	✅ †
Antigravity CLI	✅ †
Any hooks-capable agent	✅ — point it at notify.sh

† Gemini CLI and Antigravity route tool-permission prompts through an observability-only hook — the banner shows the prompt, but the Allow / Deny click still has to happen in the agent's own terminal. Claude Code and Codex permission events can be approved from the panel directly.

Platforms: macOS — full app with panel, click-to-focus banners, auto-update, quota tracking, voice. Linux (PulseAudio / ALSA / libnotify) and Windows (Git Bash / WSL) get audio + basic notifications via notify.sh only.

Install

macOS

Download the latest release from GitHub Releases — pick the .tar.gz matching your Mac's architecture (arm64 for Apple Silicon, x86_64 for Intel), expand, and drag StackNudge.app into ~/Applications/.

CLI shortcut (requires gh):

ARCH=$(uname -m)
gh release download --repo StackOneHQ/stack-nudge --pattern "stack-nudge-*-macos-${ARCH}.tar.gz*"
shasum -a 256 -c stack-nudge-*-macos-${ARCH}.tar.gz.sha256
tar xzf stack-nudge-*-macos-${ARCH}.tar.gz
mv StackNudge.app ~/Applications/
open ~/Applications/StackNudge.app

On first launch, stack-nudge runs a one-screen wizard:

1. Detects which agents you have configured (~/.claude, ~/.cursor, ~/.gemini).
2. Wires their hook configs to notify.sh.
3. Registers itself + the voice engine as launchd agents so they start at login.

Everything is self-contained inside the .app — no Xcode CLT, no Python, no shell-script bootstrap required. The bundle ships with a portable Python + stackvox (the offline voice engine) already installed. The Kokoro voice model downloads lazily the first time you enable voice notifications.

Subsequent releases install automatically via the in-app auto-updater (Settings → "Update available · vX.Y.Z" when a new release exists).

Linux / Windows

These platforms get the audio + libnotify path only — no panel, no click-to-focus, no auto-update. The shell installer is what wires notify.sh into agent hooks:

git clone https://github.com/StackOneHQ/stack-nudge.git
cd stack-nudge
./install.sh

Prerequisites: Python ≥ 3.10 (the bundled voice engine stackvox requires it).

The installer auto-wires hooks for every detected agent — Claude Code (~/.claude), Cursor (~/.cursor), Codex (~/.codex), Gemini CLI (~/.gemini), and Antigravity CLI (~/.gemini/antigravity-cli). Any other hooks-capable agent can be wired by hand — see Manual setup below.

From source (macOS dev)

If you're working on stack-nudge itself and want to build from source rather than download a release:

git clone https://github.com/StackOneHQ/stack-nudge.git
cd stack-nudge
./install.sh

Same script as Linux/Windows; on macOS it additionally builds and installs the panel .app. Requires Xcode CLT. See Development for the inner-loop tools.

How it works

Each supported agent has a hooks system. stack-nudge registers these hooks:

Agent	Event	What happens
Claude Code	Stop	Banner when the turn ends
Claude Code	PermissionRequest	Banner when Claude pauses for approval
Cursor	stop	Banner when agent turn ends
Gemini CLI	session end	Banner when agent finishes