nudgy

What is Nudgy?

Nudgy is a free, open-source macOS menu bar app that sends you native notifications when AI coding agents like Claude Code finish a task, need permissions, or ask a question. It sits in your menu bar and watches your agent sessions so you can context-switch to other work without constantly checking your terminal.

Nudgy is privacy-first and fully local — your conversations and code never leave your machine. No telemetry, no analytics, no remote logging. The only network activity is receiving hook events from your own Claude Code process over 127.0.0.1.

Currently supports Claude Code (CLI, VS Code, Desktop App), with architecture designed for additional AI coding agents (Aider, Codex CLI, Cursor, etc.) in the future.

Key Features

• Floating popup notifications — 5 visual presets (Minimal, Pill, Glass, Card, Banner), configurable screen position
• Menu bar session tracker — live session indicators, attention alerts with "Go" button, per-session token usage
• Multi-session support — color-coded sessions with real-time state (working, done, waiting, error)
• Smart notification suppression — prevents notification fatigue during rapid-fire agent events
• Configurable sound alerts — different sounds mapped to different event types
• Token usage tracking — parses Claude Code transcripts to display tokens consumed per session
• Zero external dependencies — built entirely with native macOS frameworks (SwiftUI, AppKit, Network.framework)
• Per-notification toggles — enable or disable specific event types individually

Menu Bar

Track all your active Claude Code sessions at a glance. Sessions needing attention float to the top with a "Go" button to jump straight to the right terminal window.

Popup Presets

Pick the notification style that fits your workflow — from a tiny dark chip to a full macOS-style banner.

Installation

Download (Recommended)

Grab the latest .dmg from GitHub Releases, open it, and drag Nudgy to Applications.

Build from Source

git clone https://github.com/Hamma111/nudgy.git
cd nudge
make package
open .build/release/Nudgy.app

Requirements: macOS 14.0+ (Sonoma or later), Swift 5.9+

How It Works

Nudgy runs a lightweight HTTP server on 127.0.0.1:9847 that listens for Claude Code hook events. All requests are authenticated with a per-install token stored in macOS Keychain. When Claude Code fires a hook event, Nudgy receives the JSON payload and shows the appropriate notification.

Claude Code ──hook──> POST http://127.0.0.1:9847/event?token=... ──> Nudgy ──> Floating Popup

Automatic Setup

Nudgy automatically installs the required hooks into your ~/.claude/settings.json on first launch, including a unique auth token. Hooks are refreshed on every launch to keep the token current.

Manual Setup

If you prefer to configure hooks yourself:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://127.0.0.1:9847/event?token=YOUR_TOKEN"
          }
        ]
      }
    ]
  }
}

Nudgy hooks into these Claude Code events: Stop, StopFailure, Notification, PermissionRequest, SessionStart, SessionEnd.

Supported Events

Architecture

Nudgy is built with SwiftUI + AppKit using zero external dependencies:

See the architecture directory for detailed design docs.

Building from Source

make build      # Release build
make debug      # Debug build
make test       # Run all tests
make clean      # Clean build artifacts
make package    # Create .app bundle
make dmg        # Create distributable DMG

Privacy

Nudgy is fully local. Your conversations, code, and session data never leave your machine. There is no telemetry, no analytics, no crash reporting, and no remote logging. The only network activity is the localhost HTTP server (127.0.0.1) receiving hook events from your own Claude Code process. Nothing is sent to the internet.

The source code is open — you're welcome to audit every line.

FAQ

Does Nudgy read my code or conversations?

No. Nudgy only receives structured hook event payloads (event type, session ID, timestamps) from Claude Code. It does not read your source files, conversation history, or terminal output. The only content it parses is the Claude Code transcript file for token counts, and that data stays entirely on your machine.

Does Nudgy work with AI coding agents other than Claude Code?

Currently Nudgy supports Claude Code (CLI, VS Code extension, and Desktop App). The architecture uses a generic HTTP hook protocol, so support for other agents like Aider, Codex CLI, and Cursor can be added in the future.

Does Nudgy send any data to the internet?

No. Nudgy binds exclusively to 127.0.0.1 (localhost). It makes no outbound network requests. There is an optional Usage Quota feature that, if enabled by the user, fetches quota info from the Anthropic API — but this is off by default and requires explicit opt-in.

Is Nudgy free?

Yes. Nudgy is free and open-source under the MIT License.

What macOS versions are supported?

macOS 14.0 (Sonoma) and later. Nudgy uses SwiftUI and modern Apple frameworks that require macOS 14+.

How do I uninstall Nudgy?

Quit Nudgy from the menu bar, then delete Nudgy.app from your Applications folder. Nudgy will automatically clean up its hooks from ~/.claude/settings.json when you quit.

Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

License

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