Get notified when a coding agent finishes or needs approval

To get notified when a coding agent finishes or needs approval, turn on its built-in alerts or add a hook that runs on those events. If you’ll be away from the computer, send the alert to your phone. Test it before you leave, because an agent waiting for approval does nothing until you answer.

This guide uses Claude Code for its examples. Keeping the computer awake has its own guide. Mono by Reunified sends these alerts for agents you run through it, but the method works with any setup.

1. Decide which agent events need an alert

Three events matter:

If you set up only one alert, make it the permission alert.

2. Turn on alerts in Claude Code

Claude Code sends a notification when it finishes or pauses for permission while you seem to be away. It shows desktop notifications by default only in Ghostty, Kitty and iTerm2 (terminal setup). Elsewhere, set preferredNotifChannel to "terminal_bell" in ~/.claude/settings.json to ring the bell. In tmux, add set -g allow-passthrough on to ~/.tmux.conf and reload it.

For your own sound or command, add hooks to the same file. The Notification event takes matchers such as permission_prompt (an approval has waited about six seconds) and idle_prompt (Claude finished about a minute ago and you haven’t typed since). On a Mac, this plays a different sound for each:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Hero.aiff" }]
      }
    ]
  }
}

The hooks guide also has desktop notification commands for macOS, Linux and Windows. Other agents differ, so check their documentation.

3. Send the alert to your phone

Three routes reach a phone:

• The agent’s own app. With Claude Code’s Remote Control active, run /config and turn on “Push when Claude decides”, “Push when actions required”, or both. It needs an eligible plan and the Claude app signed in to the same account, with notifications allowed.
• A hook that sends a push message, for example with curl to a push service whose app is on your phone.
• A companion app that relays session events from the computer.

Every route needs the computer on, awake and online, with the agent still running. Keep any hook token in ~/.claude/settings.json, not in the project’s .claude/settings.json, which can be committed to the repository.

4. Keep alert text private on a lock screen

Anyone near a locked phone can read its previews. Keep secrets, file contents and log lines out of hook messages. Send only the event and project name: for a made-up project called “invoice-export”, “invoice-export: approval needed” is enough. On iPhone, open Settings > Notifications and set Show Previews to When Unlocked. Android can hide sensitive content on the lock screen too, though the option’s name varies by phone.

In Mono, a finished alert shows the agent’s last message, shortened if it’s long. A permission alert shows the request as the agent describes it, often the command.

5. Test with a harmless task before you leave

On your home computer, start a session named “invoice-export check” and ask the agent to run the tests and report any failure without changing files. The agent asks before running commands, so it requests npm test. On the computer, open another screen or app, then lock your phone and go to another room.

In Mono, expect:

1. An “Agent permission request” alert naming the test command.
2. Pressing the alert opens that session, where you choose Allow. A later request sends its own alert.
3. “Agent finished in “invoice-export check”” with the agent’s last message, such as “One test in dates.test.ts fails on time zones. I didn’t change any files.”

Then run a second task with the session open on your phone: no alert arrives while you watch. Before you go out, make sure no device has the session on screen.

6. Fix alerts that don’t arrive

In Mono, open Settings > Notifications and check “All notifications”, “Code” (finished and stopped sessions), “Permission requests” and “Send to your other devices”. All are on by default. Alerts come from the computer that runs the agent, so keep Mono running there.

Before approving from your phone, read what to check in a permission request. Coding agents from your phone covers the rest of the setup. Mono isn’t available yet, but you can join the waitlist.