Lower noise
Routine operations collapse into milestones instead of individual alerts.
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
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.
Clear urgency
Questions and failures sound different from progress.
Actionable speech
Every interruption tells the listener what to do next.
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 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 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.
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.”
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.
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.
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
- 01
Source
Name the session or task in language the listener can distinguish.
- 02
State change
Explain what became true: waiting, blocked, failed, passed, or finished.
- 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
Give your agents a voice.
Keep the context. Get on with your work.
Download for Mac
Includes 14 days of free Heard. No card needed.
