Claude Smart Notifier

https://github.com/user-attachments/assets/5da68f17-e8fd-4366-bc6e-96da649fcef8

The problem

You run five Claude threads across three projects. One of them finished ten minutes ago and is waiting for a decision. You find out only when you happen to click on it. Work stalls.

Related MCP server: Claude Code Notification Hooks

The fix

Every thread pings you, with the project name and one ultra-short line saying exactly what it needs. Details stay in the chat.

✅  Website redesign     Done                Homepage ready, review it
🟡  Q3 report            Needs your answer   Use March or April figures?
🔴  Mobile app           Urgent              Build failed — need API key

Highlights

• Works in Claude Desktop (chats, Projects, Cowork) and Claude Code

• macOS and Windows (Linux via notify-send)

• One-click install, settings in Claude's UI, no config files

• Zero dependencies, no accounts, no servers. Your notification text never leaves your computer

• Update alerts: once a day it checks GitHub and pings you when a new version is out (can be turned off)

• Set up once: one line in your Claude instructions and every thread, in every project, pings you

⚡ Claude Desktop: 3 steps to make it work

Claude Code users: just install the plugin, nothing else. In Claude Desktop (chats, Projects, Cowork) all three steps are required, because of how the app works:

1. Install the extension. Download claude-smart-notifier.mcpb → double-click → Install.

2. Tell Claude to use it (once). Claude Desktop loads extension tools on demand and doesn't pass their instructions to threads, so the model won't call notify unless told. Paste this into Settings → Your Claude → Instructions:

Always: when you finish a task, and whenever you need my answer, decision, data or access, call the `notify` tool (Claude Smart Notifier) once as your very last action — this is required in every chat and project. The tool is often deferred: if it isn't loaded, load it first with tool search (query "notify"). Arguments: project = the Claude Project name (not the thread name), thread = this thread's name, level = done / question / urgent, lang = your reply language, message = max 40 chars saying what I must do (the gist of your "What's next?" — end every long reply with a 1–2 sentence "What's next?" line telling me exactly what I need to do, or that nothing is needed). Only if no notify tool exists at all (phone or web without my computer), skip it silently.

3. Run threads on your computer. Only threads linked to your computer can reach the extension:

• send messages from Claude Desktop on that computer, or

• on the web or phone, pick your computer under + → Devices before sending.

Threads running purely in the cloud (started on web/phone without a device, or cloud "coordinator" agents) can't call notify. If such an agent needs to ping you, have it start a short thread linked to your computer whose only job is to call notify.

Keep in mind: the computer must be on with Claude Desktop open · new threads only (open threads don't see newly installed tools) · while you record or share the screen, macOS hides banners (they still land in Notification Center).

📦 Install

Claude Desktop (macOS / Windows): one click

1. Download claude-smart-notifier.mcpb

2. Double-click it. Claude opens the install dialog, then click Install

3. (optional) Settings → Extensions → Claude Smart Notifier: language (auto = same as the thread, 48 languages), sounds, mute

Do I need to put any files on my computer? No. The .mcpb is a Claude Desktop extension: Claude installs it and runs it with its own built-in Node.js. When a new version is out you get a notification; download the new .mcpb from Releases and install it over the old one. Nothing to configure by hand.

Start a new chat and give it something that takes a while. You'll get pinged when it's done.

Claude Code

/plugin marketplace add vjvasiljev/claude_smart_notifier
/plugin install smart-notifier@claude-smart-notifier

Restart Claude Code.

🤖 Ask Claude to install it

Paste this into Claude (Desktop/Cowork with access to your computer, or Claude Code):

Install Claude Smart Notifier for me: https://github.com/vjvasiljev/claude_smart_notifier — follow INSTALL.md in that repo.

Claude follows INSTALL.md: it downloads the bundle and opens the installer (Desktop) or runs the plugin commands (Code). You only click Install.

Requires Node.js ≥ 16.

git clone https://github.com/vjvasiljev/claude_smart_notifier.git

{
  "mcpServers": {
    "smart-notifier": {
      "command": "node",
      "args": ["/absolute/path/to/claude_smart_notifier/server/index.js"],
      "env": { "NOTIFY_LANG": "en" }
    }
  }
}

Make every project and thread ping you

For Claude Desktop, paste this into Settings → Your Claude → Instructions (applies to every chat and project):

Always: when you finish a task, and whenever you need my answer, decision, data or access, call the notify tool (Claude Smart Notifier) once as your very last action — this is required in every chat and project. The tool is often deferred: if it isn't loaded, load it first with tool search (query "notify"). Arguments: project = the Claude Project name (not the thread name), thread = this thread's name, level = done / question / urgent, lang = your reply language, message = max 40 chars saying what I must do (the gist of your "What's next?" — end every long reply with a 1–2 sentence "What's next?" line telling me exactly what I need to do, or that nothing is needed). Only if no notify tool exists at all (phone or web without my computer), skip it silently.

Start a new thread afterwards.

Check it works

node server/index.js --test

Shows one notification of each level.

⚙️ Settings

In Claude Desktop, change these in Settings → Extensions. Elsewhere, set them as environment variables.

Advanced: custom emoji, labels and sounds per level

{
  "levels": {
    "done":     { "emoji": "🟢", "sound": "Hero",  "label": "Finished" },
    "question": { "emoji": "🟡", "sound": "Ping",  "label": "Your turn" },
    "urgent":   { "emoji": "🔴", "sound": "Basso", "label": "Blocked" }
  },
  "emojiInTitle": true
}

macOS sounds: Basso Blow Bottle Frog Funk Glass Hero Morse Ping Pop Purr Sosumi Submarine Tink. On Windows each level uses a system sound (Default / Reminder / IM), and 🔴 urgent stays on screen until dismissed.

🩺 Troubleshooting

❓ FAQ

How do I get notified when Claude Code finishes a task? Install the Claude Code plugin (two commands above). Every session will ping you when it's done or waiting for input.

How do I know when a Claude Desktop / Cowork / Projects chat is waiting for me? Install the .mcpb extension. Any thread that needs your decision sends a 🟡 notification with the project name.

Does it work with many parallel threads and projects? That's what it's built for. Each notification starts with the project name, so you know where to go.

Does it send my data anywhere? No. Your notifications are shown locally via the OS. The only network request is a once-a-day version check to GitHub's public releases API (no data about you, can be turned off). No telemetry.

Can it play a different sound per level? Yes. Set sounds in the extension settings, or emoji/labels/sounds per level via NOTIFY_CONFIG.

My language isn't there. Add one line to LABELS in server/index.js and open a PR.

🛠 How it works

A ~350-line, zero-dependency Node.js MCP server with one tool:

notify(title, message, level = done | question | urgent, subtitle?, sound?)

• Speaks MCP over stdio

• Calls the native notification API: osascript (macOS), PowerShell WinRT toast (Windows), notify-send (Linux)

• Returns MCP instructions, so every connected Claude thread knows to call notify once at the end of a task, with a ≤ 40-character message in your language

server/index.js           MCP server (the whole thing)
manifest.json             Claude Desktop extension manifest (.mcpb)
.claude-plugin/           Claude Code plugin + marketplace
.mcp.json                 MCP config used by the Claude Code plugin

🗺 Roadmap

• Verify on Windows (help wanted)

• Click a notification to open the exact thread

• Quiet hours

• Phone push (ntfy / Pushover) as an optional channel

• Per-project sounds

• Native dropdown for language (when Claude extension settings support it)

Ideas and PRs welcome. See CONTRIBUTING.md.

License

MIT © vjvasiljev

Not affiliated with or endorsed by Anthropic. "Claude" is a trademark of Anthropic, PBC.