# Receive notifications for designated coding agent events
**Author:** Cooper Veysey
**Published:** 2025-10-27 12:00:00+00
**Category:** Agents
## Introduction
Last week I shared some reflections from my first few weeks using agentic coding tools [(link)](/blogs/agentic-systems-first-impressions?utm_source=coding_agent_notifications&utm_medium=blog_link). Today I am going to share some details about a problem that I encountered repeatedly while using these tools, as well as a solution that I built to address that problem.
## What prompted the creation of this tool?
You assign a coding agent a long-running task and switch to Slack to answer some messages. You start and finish a huddle and eventually return to your IDE to find that the coding agent has been sitting idle for several minutes, because it requires your direction on a task or authorization to use a tool. If you had known that the agent required your input, then you would have provided the required input quickly and had the agent back to work several minutes prior. Instead material time and output have been lost to unnecessary latency.
When Claude Code requires input from a human, by default that is communicated exclusively via Claude Code outputting a message to the terminal. It is not otherwise announced that Claude Code requires feedback in order to continue its work. No sound plays, no visual notification displays outside of what is displayed via the terminal.
That means that if a human is not actively monitoring their terminal, there is a delta between when an agent requires feedback and when a human becomes aware of that. Repeated dozens of times across a workday, the cumulative cost of these idle intervals adds up. A few minutes here and there compounds into hours of idle agent time, which can prove extremely expensive as measured by throughput.
This was happening to me often enough that I was compelled to explore how other folks had accounted for this. The consequences felt significant enough that I was sure that a quality solution to the problem must exist already. I was excited to find and start benefitting from that solution.
I validated that I was not the only person to experience this problem, for example [this Reddit thread](https://www.reddit.com/r/ClaudeAI/comments/1ll8f3d/can_claude_code_play_a_sound_when_it_requires_an/) is dedicated to the problem and features comments like:
> Sometimes (Claude Code) works for a couple of minutes and I don't want to stare at the screen waiting for it to (stop) inevitably and ask me something to approve etc. Is there a way to play a sound when it requires my attention?
> Getting a sound alert when Claude Code needs your approval would totally keep you from staring at the screen all day waiting for the next prompt.
I learned that several coding agent alert solutions exist, but none were exactly what I was looking for. Some require manual JSON editing. Others offer audio alerts but not visual notifications, which is not viable for folks like myself that are frequently on calls and often need to silence their audio notifications. So I decided to build what I was looking for.
## What does the tool do?
- Our tool helps ensure that you are alerted as early as possible whenever a coding agent might benefit from your input. It does this via customizable audio and visual notifications that are triggered by different coding agent events.
- Our tool frees you from having to actively monitor whether or not a coding agent requires your input.
## How does it work?
Our solution takes advantage of Claude Code hooks to deliver notifications when designated events occur. Anthropic defines these hooks as "user-defined shell commands that execute at various points in Claude Code's lifecycle. Hooks provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them" ([source](https://docs.claude.com/en/docs/claude-code/hooks-guide)).
**Hook events that our solution currently accounts for**
- [Notification](https://docs.claude.com/en/docs/claude-code/hooks-guide#hook-events-overview) – Runs when Claude Code sends notifications.
- [Stop](https://docs.claude.com/en/docs/claude-code/hooks-guide#hook-events-overview) – Runs when Claude Code finishes responding.
- [PreToolUse](https://docs.claude.com/en/docs/claude-code/hooks-guide#hook-events-overview) – Runs before tool calls (permission prompts).
- [PostToolUse](https://docs.claude.com/en/docs/claude-code/hooks-guide#hook-events-overview) – Runs after tool calls complete.
- [SubagentStop](https://docs.claude.com/en/docs/claude-code/hooks-guide#hook-events-overview) – Runs when subagent tasks complete.
**Some details on what happens when our app is installed**
Script files are added to ~/.claude/scripts/:
- smart-notify.sh — Parses hook event metadata, invokes afplay for audio playback and
terminal-notifier for macOS notifications.
- select-sound.sh — Determines which audio file to play based on event type and project.
- read-config.sh — Loads notification preferences from audio-notifier.yaml, and exports
them as shell environment variables.
- audio-notifier-uninstall.sh — Removes hooks from settings.json, deletes installed
files, creates a timestamped settings.json backup.
The below files are added to ~/.claude/:
- audio-notifier.yaml — Configuration file storing event-specific notification settings,
audio file paths, and Focus mode behavior.
- .sounds-enabled — Flag file checked by smart-notify.sh to enable/disable notifications.
- voices/global/\*.mp3 — Pre-generated audio files for default notification sounds.
- terminal-notifier.app — macOS utility for delivering native system notifications via
NSUserNotificationCenter.
## Customization options
We created a Tauri app to make it as easy as possible for users to customize their coding agent notifications experience. Via our GUI:
- Visual notifications can be turned on and off on a per event basis.
- Audio alerts can be turned on and off on a per event basis.
- You can arrange for different audio to play on a per event basis.
- You can upload custom audio for your alerts.
- You can customize how [Apple "Focuses"](https://support.apple.com/guide/mac-help/change-focus-settings-mchlff5da36d/mac) (Do Not Disturb, Work, Sleep) affect your notifications.
These settings are stored locally in YAML and can be modified either through the GUI or directly via the config file.
## Video that showcases the tool
## Installation
It takes less than 60 seconds to install and start using our solution. The app needs to be opened once in order to enable notifications, after that the app does not need to be running in order for notifications to fire. Claude Code sessions that were started before the application is run for the first time will need to be restarted, due to the fact that ~/.claude/settings.json is read once at session startup.
## Accounting for [Apple Focuses](https://support.apple.com/guide/mac-help/change-focus-settings-mchlff5da36d/mac)
Our visual notifications are delivered via terminal-notifier, a utility for delivering native macOS notifications. By default, visual notifications are suppressed if a Focus (Do Not Disturb, Work, Sleep) is active. Follow the instructions below if you would like for our visual notifications to display regardless of whether a Focus is active.
- Open Focus Settings.
- Select the Focus that you want to allow coding agent visual notifications for.
- From there select **Allowed Apps** from the **Allow Notifications** section, and add terminal-notifier to that list.
## Future plans for the tool
If other folks wind up using the tool and have feedback, I will definitely consider accounting for said feedback. I am also open to open-sourcing the tool.
I hope that the tool proves useful to at least a few other individuals — that would bring me a ton of joy. I enjoyed building this and learned a lot in the process. I continue to be amazed by what these coding agent tools can do.
**Backlog**
- Support for additional coding agents
- Support for Linux
- Allow for per-project customization
- Notification badges, subtle dock indicators
- Slack notifications, phone notifications (e.g. see https://justin.searls.co/posts/notify-your-iphone-or-watch-when-claude-code-finishes)
- "Smart" escalation rules (e.g. if no response after x time, ping y other channel)
## Thank you for your time
If you have any questions or want to connect on anything that I wrote about above, please [email me](mailto:cooper@veyseysoftwaresolutions.com) or [book some time on my calendar](https://calendar.google.com/calendar/appointments/schedules/AcZssZ041TFFhKz0LzQydfOipmZ3l8K-22DadOWnsRMPnLkS8TjaDIreyZ8fFxAimnDxsCeimFSvnY_3). Any and all feedback is of course so appreciated.