> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop Notifier

> OS-native desktop notifications for macOS and Linux

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

<Note>
  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.
</Note>

## Configuration

Add the desktop notifier to your `agent-orchestrator.yaml`:

```yaml theme={null}
plugins:
  notifier:
    name: desktop
    config:
      sound: true  # Optional: enable/disable sound alerts
```

### Configuration Options

<ParamField path="sound" type="boolean" default={true}>
  Enable or disable sound alerts for urgent notifications. When enabled, notifications with `urgent` priority will play the default system sound.
</ParamField>

## How It Works

### Priority Mapping

The plugin maps event priorities to notification behavior:

<AccordionGroup>
  <Accordion title="urgent">
    * Plays sound alert (if `sound` is enabled)
    * Uses critical urgency on Linux
    * Title prefixed with "URGENT"
  </Accordion>

  <Accordion title="action">
    * Normal notification
    * No sound
    * Standard system behavior
  </Accordion>

  <Accordion title="info / warning">
    * Silent notification
    * Standard system behavior
  </Accordion>
</AccordionGroup>

### 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:

```applescript theme={null}
display notification "message" with title "title" sound name "default"
```

<Info>
  The plugin automatically escapes special characters in titles and messages to prevent AppleScript injection.
</Info>

### Linux

Uses `notify-send` with urgency flags:

```bash theme={null}
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

```yaml theme={null}
plugins:
  notifier:
    name: desktop
```

### Disable Sound Alerts

```yaml theme={null}
plugins:
  notifier:
    name: desktop
    config:
      sound: false
```

### Per-Project Override

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="No notifications appearing on macOS">
    **Check notification permissions:**

    1. Open System Preferences → Notifications
    2. Find "Terminal" or your terminal emulator
    3. Enable "Allow Notifications"

    **Verify osascript works:**

    ```bash theme={null}
    osascript -e 'display notification "Test" with title "Test"'
    ```
  </Accordion>

  <Accordion title="No notifications appearing on Linux">
    **Install notify-send:**

    Ubuntu/Debian:

    ```bash theme={null}
    sudo apt install libnotify-bin
    ```

    Fedora:

    ```bash theme={null}
    sudo dnf install libnotify
    ```

    **Test notify-send:**

    ```bash theme={null}
    notify-send "Test" "Message"
    ```
  </Accordion>

  <Accordion title="Sound not playing">
    * Verify `sound: true` in your config
    * Check system sound is enabled
    * Only `urgent` priority events play sound
    * Test with system sound settings
  </Accordion>

  <Accordion title="Notifications appear but are cut off">
    This is a platform limitation. Most systems truncate long notification messages. Keep event messages concise (under 200 characters recommended).
  </Accordion>
</AccordionGroup>

## Source Code

View the plugin source:

* Package: `@composio/ao-plugin-notifier-desktop`
* Location: `packages/plugins/notifier-desktop/src/index.ts`

## Related

* [Slack Notifier](/plugins/notifier/slack) - Send notifications to Slack
* [Webhook Notifier](/plugins/notifier/webhook) - Generic HTTP webhook notifications
* [Composio Notifier](/plugins/notifier/composio) - Unified notifications via Composio
* [Notifier Plugin Interface](/api/notifier) - Technical interface documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.