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

# Notifications

> Configure how agents notify you about important events

## Overview

Mux can send system notifications to alert you about important events. Notifications appear as native OS notifications (macOS Notification Center, Windows Toast, Linux notification daemon) and work even when Mux is in the background. Clicking a notification takes you directly to the workspace that sent it.

There are two ways to receive notifications:

1. **Automatic notifications** — Toggle the bell icon in the workspace header to get notified when the agent completes a response. Use <kbd>Ctrl+Shift+N</kbd> (<kbd>⌘+Shift+N</kbd> on macOS) to toggle quickly.

2. **Agent-triggered notifications** — The `notify` tool lets agents send notifications for specific events. You control when agents use this through prompts or scoped instructions.

## Quick examples

```text theme={null}
Notify me when you have this test passing.
```

```text theme={null}
Notify me before finishing your message.
```

```text theme={null}
Notify me once you're halfway through.
```

```text theme={null}
Work on these 5 tasks. Notify me after each one completes.
```

## Controlling notification behavior

### Via Tool scoped instructions (recommended)

The recommended way to configure the `notify` tool is via a `Tool: notify` scoped instruction in your system prompt or AGENTS.md:

```markdown theme={null}
## Tool: notify

- Notify on CI failures or deployment issues
- Notify when waiting for user input longer than 30 seconds
- Do not notify for routine status updates
- Use `todo_write` for routine progress updates instead
```

See [Instruction Files](/agents/instruction-files) for more on scoped instructions.

### Disable notifications for a specific agent

If you have an agent that should not interrupt you (e.g. a `review` agent), remove `notify` from that agent's tool policy:

```md theme={null}
# .mux/agents/review.md

---

name: Review
description: Terse reviewer-style feedback
base: exec
tools:
remove: - notify

---

You are a code reviewer.

- Focus on correctness, risks, and test coverage.
- Prefer short, actionable comments.
```

## Platform notes

Notifications use your operating system's native notification system:

| Platform | Notification Type                               |
| -------- | ----------------------------------------------- |
| macOS    | Notification Center                             |
| Windows  | Toast notifications                             |
| Linux    | Desktop notifications (via notification daemon) |

Notification settings (sound, Do Not Disturb, etc.) are controlled by your OS preferences, not Mux.

## Tool definition

The `notify` tool definition from source:

```typescript theme={null}
notify: {
    description:
      "Send a system notification to the user. Use this to alert the user about important events that require their attention, such as long-running task completion, errors requiring intervention, or questions. " +
      "Notifications appear as OS-native notifications (macOS Notification Center, Windows Toast, Linux). " +
      "Infer whether to send notifications from user instructions. If no instructions provided, reserve notifications for major wins or blocking issues. Do not use for routine progress updates — keep the todo list current instead.",
    schema: z
      .object({
        title: z
          .string()
          .min(1)
          .max(64)
          .describe("Short notification title (max 64 chars). Should be concise and actionable."),
        message: z
          .string()
          .max(200)
          .nullish()
          .describe(
            "Optional notification body with more details (max 200 chars). " +
              "Keep it brief - users may only see a preview."
          ),
      })
      .strict(),
  },
```