Claude Code notifications: know when it needs you

Claude Code can run a command of your choice whenever it is waiting for you. A few lines in your settings turn that into a desktop notification. There is one case this does not cover, and it is the one that costs the most time.

A notification when Claude needs you

Add this to ~/.claude/settings.json. On a Mac it shows a system notification:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

The Notification event fires in two situations that matter here:

• It needs your permission for a tool call and the prompt has been waiting about six seconds.
• It finished about a minute ago and you have not typed anything since.

In a terminal session these only fire when you appear to be away, so you are not notified about things you are already looking at.

A notification the moment it finishes

There is also a Stop event, which fires every time Claude finishes responding. Use the same structure with "Stop" in place of "Notification" if you want to hear about every completed turn. Be warned that this is a lot of notifications in a busy session.

What hooks cannot catch

Hooks fire when Claude Code itself does something. They cannot fire for things that happen outside it.

The common case: an agent opens a pull request and waits for the checks. A check fails on GitHub. Nothing in the session has changed, so no hook fires, the agent keeps waiting, and you find out when you happen to look.

The other case is a session that stopped on a failed push hook or test run. You get the ordinary "finished" notification, which looks the same as success.

Covering the gap

Cost Doctor watches from outside the session. It checks your open pull requests every few minutes using the GitHub command line tool, and looks for sessions that stopped on a failure and have sat idle. When it finds one, the menu bar badge turns red, a red frame appears around every screen, and a notification is sent. Each alert can be dismissed, and the frame does not block clicks.

Your own scripts can raise the same alert with one line, which is handy for deploys and nightly jobs:

echo "deploy failed" > ~/.costdoctor/alerts/deploy.txt

More on this in your agent is waiting on a check that already failed.