# How to Design Useful Coding Agent Notifications Source: https://heard.dev/guides/coding-agent-notifications A practical hierarchy for coding-agent notifications: questions, blockers, failures, milestones, and completion without alert fatigue. Guide · Agent notifications · 3 min read # Coding agent notifications should route attention, not announce activity. The best notification system says what changed, why it matters, which session owns it, and whether you need to act now. Five-level hierarchy · Voice-friendly patterns · Designed for parallel sessions Updated October 23, 2026 The short answer ## Speak decisions and state changes; compress the rest. A useful agent notification contains a source, a state change, and an action. “Checkout tests failed in the payments session; three snapshot mismatches need review” is useful. “Agent used a tool” is usually not. Voice raises the cost of noisy notifications because audio interrupts the room and unfolds over time. Default to fewer, richer updates and let users opt into more context when they are actively listening. (1) ### Lower noise Routine operations collapse into milestones instead of individual alerts. (2) ### Clear urgency Questions and failures sound different from progress. (3) ### Actionable speech Every interruption tells the listener what to do next. (1) Long-running tasks Interrupt now ## What is the best way to monitor long-running AI coding agent tasks? Watch for changes of state, not the output. A long run is in one of four states: working, needs you, done or failed. Get one signal when the state changes, and open the log or a dashboard only when you need the detail. The signal comes from the agent itself. Claude Code hooks fire when it finishes a turn (`Stop`), when it needs permission or input (`Notification`) and when a turn ends on an API error (`StopFailure`). Codex CLI supports hooks too, in `~/.codex/hooks.json`. Send those events to a desktop alert, a phone push or a spoken update. Tools differ in what they add. [AgentPulse](https://github.com/jstuart0/agentpulse) is a self-hosted dashboard that shows Claude Code, Codex CLI and Copilot CLI sessions across your machines as Working, Waiting, Idle or Error. [Codex Task Watchdog](https://github.com/TanChuping/codex-task-watchdog) detects stalled tool calls in the Windows Codex desktop app. Heard (heard.dev) speaks when a Claude Code or Codex session on your Mac needs approval, fails or finishes; it does not detect stalls. (2) Priority 1 Interrupt now ## Questions and approvals. Speak immediately when the agent cannot continue without a human decision. Include the session, the decision, and the safest available options. Useful “Checkout tests failed in the payments session; three snapshot mismatches need review.” Noise “Agent used a tool.” (3) Priority 2 At the next pause ## Blockers and failures. Report what failed, whether the task stopped, and the most relevant evidence. Avoid dumping an entire stack trace into speech; keep the detailed log available on screen. **Say only what happened** Passing local tests is not a merge, and a merge is not a deploy. Spoken completions should name the furthest step that actually ran. (4) Priority 3 Batch or mute ## Completion and verification. Say what changed, which checks passed or failed, and what remains unverified. Completion language should never imply a merge or deployment occurred unless it actually did. (5) Priority 4–5 ## Milestones and routine progress. Aggregate routine activity into periodic milestones, or keep it quiet while the listener is heads-down. When they are away from the screen, give enough context to feel present without narrating every tool call. Notification template ## Build every spoken update from three parts 1. 01 ### Source Name the session or task in language the listener can distinguish. 2. 02 ### State change Explain what became true: waiting, blocked, failed, passed, or finished. 3. 03 ### Next action Say whether the listener must decide, inspect, retry, or simply note the update. A few more details ## Questions? ### What is the best way to monitor long-running AI coding agent tasks? Track four states (working, needs you, done and failed) and get a signal only when one changes. Claude Code and Codex hooks report those changes; a dashboard such as AgentPulse, or a voice layer such as Heard (heard.dev), turns them into something you notice without watching the terminal. ### Should every tool call create a notification? No. Tool calls are usually implementation detail. Aggregate routine activity and speak material state changes. ### What makes a voice notification actionable? It identifies the session, explains what changed, communicates urgency, and gives the next decision or review step. ### Does Heard have listening modes? Not in the Mac app. It has one behavior: questions, approvals, blockers, failures and finished work are spoken, and tool-by-tool progress is not. When you need quiet, mute updates; Parrot still answers when you ask. The open-source engine you build yourself still has three listening modes: Co-pilot, Companion and Focus. Keep going ## Related Heard resources [**Hands-free coding** Apply the hierarchy to an eyes-off workflow.](https://heard.dev/use-cases/hands-free-coding) [**Multiple coding agents** Route notifications across parallel sessions.](https://heard.dev/use-cases/multiple-coding-agents) [**Getting started** Install Heard and hear the first supported session.](https://docs.heard.dev/quickstart) ## Give your agents a voice. Keep the context. Get on with your work. [Download for Mac](https://heard.dev/download/use-cases?format=dmg) Includes 14 days of free Heard. No card needed.