Configuration
Notifications & Sound
Configure desktop notifications and sound alerts for agent activity.
ChatML can notify you when important events happen — especially useful when running multiple sessions in parallel.
Desktop Notifications
When ChatML is not in focus, macOS notifications alert you about:
| Event | When |
|---|---|
| Agent completed | Claude finishes responding in a session |
| Agent error | An error occurs during agent execution |
| Plan ready | Claude has a plan ready for your approval |
Notifications are debounced per conversation (5-second throttle) to avoid notification spam during rapid agent activity.
Clicking a notification brings ChatML to the foreground and navigates to the relevant conversation.
Notifications only appear when ChatML is not the focused application. If you're actively working in ChatML, no notifications are sent.
Sound Effects
ChatML can play sound effects for agent events:
- Completion sound — Plays when an agent finishes its work
- Error sound — Plays when an error occurs
Configure sounds in Settings (Cmd+,) > Appearance > Sound Effects.
macOS Configuration
If you're not seeing notifications:
- Open System Settings > Notifications > ChatML
- Ensure notifications are allowed
- Choose your preferred notification style (Banners or Alerts)