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 Ctrl+Shift+N (⌘+Shift+N 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

Notify me when you have this test passing.

Notify me before finishing your message.

Notify me once you're halfway through.

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:

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

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

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(),
  },