Claude Code Needs Notifications
This is Part 1 of the Claude Code Notifier series. (4 parts total)
I run Claude Code with personas and documented execution plans, processing tasks sequentially and in parallel. It takes longer, but the results are better. I usually have four terminals open, each running a different task. Claude does its thing while I do other work.
The problem was what came next.
Missed Moments
I'd come back to find it already done. No idea when it finished. 10 minutes ago? 30 minutes? Just a blinking cursor.
Claude: (working hard...)
Me: (doing other work)
Me: (10 min later) "Oh, it's done"
The permission requests were worse. Claude needs approval to create files, but it waits silently. I wasted an hour not knowing.
Claude: "I'd like to create a file. Allow?"
Me: (unaware for 1 hour...)
Me: "Why isn't this done yet?"
I thought I'd just check the terminal more often. But switching between four sessions constantly got tedious.
Just Notify Me
One day it hit me. Just send a notification when it's done.
Obvious in hindsight. I probably thought "I can handle checking myself." I couldn't.
So I built it.
Three notifications were enough:
| Event | Notification |
|---|---|
| Task completed | "Done" |
| Permission needed | "Need approval" |
| Waiting for input | "What should I do?" |
Started with five, ended up with three. More would be annoying.
Ignore Short Tasks
Notifications on every response would drive me crazy. "Hi" — ding. "Thanks" — ding. That's not notifications, that's torture.
So I set a 20-second threshold. Picked the number arbitrarily. Works fine.
# Default is 20 seconds
# Change it if you want
/notifier duration 30
Installation
Run this in your terminal:
git clone https://github.com/js-koo/claude-code-notifier.git && cd claude-code-notifier && ./install.sh
That's it. No config needed. Just works.
I don't like tools with lots of settings. If I have to configure before using, I won't use it. So I made it work out of the box.
Commands
If you want to customize, use /notifier:
| Command | What it does |
|---|---|
/notifier help | Help |
/notifier status | Current settings |
/notifier lang en | English |
/notifier duration 30 | Notify only after 30s |
/notifier test | Test notification |
/notifier uninstall | Remove |
Platforms
Works on macOS, Linux, Windows. WSL too.
| Platform | Notification method |
|---|---|
| macOS | System Notification Center |
| Linux | notify-send |
| Windows | Toast notification |
| WSL2 | Toast notification |
I was going to support only macOS since that's what I use. But I got greedy. More on that in Part 3.
In Practice
Three terminals, three tasks:
[Terminal 1] Refactoring...
[Terminal 2] Writing tests...
[Terminal 3] Documentation...
I do other work.
🔔 Terminal 1 completed
🔔 Terminal 3 needs permission
🔔 Terminal 2 completed
Notifications come as things happen. No more staring at terminals.
So
Simple tool. Notifies when done. That's it.
Turned out to be quite useful. Before building it I thought "I don't really need this." After building it, I can't go without.
Next post covers how it works. There's this thing called Hooks in Claude Code.
Series:
- Part 1: Claude Code Needs Notifications (current)
- Part 2: It's All About Hooks
- Part 3: macOS Only?
- Part 4: Create pull request