Notifications

Codemux has a notification and attention system that keeps you aware of what's happening across workspaces — especially useful when running multiple agents in parallel.

Desktop Notifications

When an agent needs you, Codemux sends a desktop notification via the system notification daemon (D-Bus on Linux, native APIs on Windows / macOS):

• Agent finished — workspace ("Codemux is waiting for your review.") — when a terminal agent or an Agent Chat agent finishes its turn.
• Agent needs your input — workspace ("Approve or answer to let it continue.") — when a chat agent opens an approval or asks you a question. Terminal agents notify only when they finish.

Codemux stays quiet when you're already looking: no notification if the Codemux window is focused and the agent is in the workspace you have open, and never for a muted workspace. The notification:

• Uses normal urgency so the notification daemon (mako, dunst, GNOME Shell, KDE Plasma, …) auto-dismisses it after the configured timeout. Critical urgency would keep popups stuck on screen until manually dismissed — reserved by those daemons for non-expiring system emergencies.
• Plays an optional notification sound (toggleable — see Sound below)
• Opens the agent when clicked — see Opening the agent

Desktop notifications can be toggled in Settings → Notifications. In a browser connected through Web Remote Access, the same events arrive as an in-app toast with an Open button (and a browser notification, if you allowed them); either one opens the agent.

Opening the Agent

Clicking a desktop notification takes you to the agent that sent it, on Linux:

• Shows, unminimizes, and focuses the Codemux window via Tauri
• On Hyprland, also runs hyprctl dispatch focuswindow class:com.codemux.app for reliable window activation
• Opens the notification's workspace and the agent's pane

This means you don't have to find the window, then the workspace, when an agent finishes or needs input.

Attention Badges

Each workspace card in the expanded sidebar inbox shows a notification count badge when it has unread notifications. The collapsed rail shows only a status dot (no count), and settled rows show no badge. The count resets when you switch to that workspace.

This lets you scan the sidebar to see which workspaces have pending activity without clicking through each one.

Pane and Tab Status Indicators

Individual panes and tabs show colored status dots based on agent activity:

Only Permission pings — it's the one state that needs you — and its ring keeps it distinct in greyscale and with motion turned off. With Settings → Appearance → Reduce motion on (or your system asking for reduced motion), the animations stop.

These appear in three places:

• Pane headers — Each pane shows its own status
• Tab bar — Each tab shows the highest-priority status from its panes
• Sidebar — Each workspace shows an aggregate status (permission > working > monitoring > review > idle)

Screen readers hear a polite announcement — "‹workspace› needs you" — each time a workspace becomes blocked on you, in the main window.

See Agent Status Indicators for the full details on how status tracking works.

Sending Notifications

Agents can send notifications programmatically:

codemux notify "Build finished successfully"

The MCP server also exposes a notify tool with an optional level parameter (info or attention).

Notification Sound

Notification sound playback is implemented on all three platforms:

Toggle it in Settings → Notifications → Notification sounds. The setting syncs across devices via your account.

Settings

Two notification settings are available in Settings → Notifications:

• Desktop notifications — Toggle system notification popups on/off
• Notification sounds — Toggle the audio chime on/off

Both switches are honored by the desktop app itself, for terminal and chat agents alike.

Both settings sync across devices via your account.