Terminal Notifications — Know When Claude Code Is Done

What is it

When Claude Code finishes working and is waiting for your next prompt, it fires a notification signal. Your macOS terminal can catch that signal and turn it into a real desktop notification — the same kind you get from Messages, Slack, or Calendar. It's the banner that slides in from the top-right corner of your screen and shows up in Notification Center.

Heads up: the default Terminal.app that comes with your Mac doesn't support this. You'll need a third-party terminal like iTerm2, Kitty, or Ghostty.

Claude Code terminal config docs

What problems it solves

You kick off a big refactor in Claude Code, switch over to your browser to review a PR, and forget about it. Five minutes later you wonder "is it done yet?" so you cmd-tab back to check. It's not. You switch back. Repeat four times. That constant tab-switching breaks your flow and wastes attention.

Or you're running Claude Code in one terminal tab while working in another. There's no visual cue that it finished. You just have to remember to check, and you always check either too early or too late.

How to use it

Kitty and Ghostty — works out of the box

Kitty and Ghostty are two popular macOS terminal apps that support these notifications with zero configuration. If you use either of these, you already have this feature and might not even know it. Just run Claude Code and you'll get banners when it finishes.

iTerm2 — three settings

iTerm2 needs a quick toggle. Open Settings (Cmd+,), then go to Profiles → Terminal:

1. Scroll down to the Notifications section
2. Check "Notification Center Alerts"
3. Click "Filter Alerts" and make sure "Send escape sequence-generated alerts" is checked

That's it. Next time Claude Code finishes a task, you'll see a macOS notification banner.

Terminal.app — not supported

The default Terminal app that ships with macOS doesn't support escape-sequence notifications. If you're using Terminal.app, you have two options: switch to one of the terminals above, or use notification hooks to run a custom script (play a sound, trigger a Shortcut, send yourself a message) when Claude finishes.

Running inside tmux?

tmux swallows escape sequences by default, so the notification never reaches your terminal. Add this to your ~/.tmux.conf:

set -g allow-passthrough on

Then reload:

tmux source-file ~/.tmux.conf

Pro tips

Notification hooks and terminal notifications aren't either/or. You can have both. The terminal shows the banner while a hook does something extra, like playing a custom sound or logging to a file.

References

• Claude Code terminal configuration
• Claude Code notification hooks
• iTerm2 · Kitty · Ghostty