Skip to main content
The Desktop notifier plugin sends notifications through your operating system’s native notification system. On macOS, it uses osascript to display notifications via AppleScript. On Linux, it uses notify-send.

​
Overview

The Desktop notifier provides OS-native desktop notifications with support for:
  • Sound alerts for urgent notifications
  • Priority-based notification urgency
  • Automatic platform detection (macOS/Linux)
  • Session-based notification grouping
  • Graceful fallback on unsupported platforms
Desktop notifications do not support click-through URLs natively. On macOS, osascript’s display notification command lacks URL support. Consider using terminal-notifier if you need click-to-open functionality.

​
Configuration

Add the desktop notifier to your agent-orchestrator.yaml: 
plugins:
  notifier:
    name: desktop
    config:
      sound: true  # Optional: enable/disable sound alerts

​
Configuration Options

​
sound
boolean
default:true
Enable or disable sound alerts for urgent notifications. When enabled, notifications with urgent priority will play the default system sound.

​
How It Works

​
Priority Mapping

The plugin maps event priorities to notification behavior:
  • Plays sound alert (if sound is enabled)
  • Uses critical urgency on Linux
  • Title prefixed with “URGENT”
  • Normal notification
  • No sound
  • Standard system behavior
  • Silent notification
  • Standard system behavior

​
Notification Format

Title Format: 
[URGENT|Agent Orchestrator] [session-id]
Message: The event message is displayed as-is. Actions: When actions are present, they are rendered as text labels in the notification body since native OS notifications don’t support interactive buttons: 
Your notification message

Actions: Approve | Reject | View Details

​
Platform Support

​
macOS

Uses osascript to execute AppleScript commands: 
display notification "message" with title "title" sound name "default"
The plugin automatically escapes special characters in titles and messages to prevent AppleScript injection.

​
Linux

Uses notify-send with urgency flags: 
notify-send --urgency=critical "title" "message"

​
Other Platforms

On unsupported platforms (Windows, etc.), the plugin logs a warning and performs no operation: 
[notifier-desktop] Desktop notifications not supported on <platform>

​
Usage Examples

​
Basic Configuration

plugins:
  notifier:
    name: desktop

​
Disable Sound Alerts

plugins:
  notifier:
    name: desktop
    config:
      sound: false

​
Per-Project Override

projects:
  - name: my-project
    plugins:
      notifier:
        name: desktop
        config:
          sound: true  # Enable sound only for this project

​
Event Types

The desktop notifier handles these orchestrator events:
  • session.started - Agent session has started
  • session.completed - Agent session completed successfully
  • session.failed - Agent session failed
  • pr.created - Pull request created
  • pr.updated - Pull request updated
  • ci.failed - CI checks failed
  • review.requested - Code review requested
  • human.required - Human judgment needed

​
Troubleshooting

Check notification permissions:
  1. Open System Preferences → Notifications
  2. Find “Terminal” or your terminal emulator
  3. Enable “Allow Notifications”
Verify osascript works:
osascript -e 'display notification "Test" with title "Test"'
Install notify-send:Ubuntu/Debian:
sudo apt install libnotify-bin
Fedora:
sudo dnf install libnotify
Test notify-send:
notify-send "Test" "Message"
  • Verify sound: true in your config
  • Check system sound is enabled
  • Only urgent priority events play sound
  • Test with system sound settings
This is a platform limitation. Most systems truncate long notification messages. Keep event messages concise (under 200 characters recommended).

​
Source Code

View the plugin source:
  • Package: @composio/ao-plugin-notifier-desktop
  • Location: packages/plugins/notifier-desktop/src/index.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us