# How the Omarchy Notification System Routes Messages: CLI to QML Architecture

> Discover how the Omarchy notification system routes messages. Learn about the CLI to QML architecture and message persistence for desktop toasts.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-13

---

**Omarchy routes all notifications through the `omarchy-notification-send` CLI wrapper to a Quickshell-based daemon via IPC, persisting messages as JSON files in `~/.local/state/omarchy/notifications/` before rendering them as desktop toasts.**

The Omarchy notification system replaces traditional freedesktop `notify-send` workflows with a robust, file-backed architecture designed for reliability and Do-Not-Disturb consistency. Unlike standard Linux notification daemons, Omarchy centralizes message routing through a dedicated CLI helper and a Quickshell QML service. This architecture ensures that every notification is recorded to disk, respects DND settings, and maintains a persistent history even when the graphical toast is suppressed.

## Message Entry Point: The omarchy-notification-send Wrapper

All internal Omarchy code uses the **`omarchy-notification-send`** binary located at `bin/omarchy-notification-send` to dispatch notifications. You should never invoke the raw `notify-send` command directly; the wrapper handles this internally according to the Omarchy source code.

The wrapper performs essential bookkeeping before forwarding the message.

- Sanitizes notification content and metadata
- Respects current Do-Not-Disturb (DND) settings
- Formats the payload into JSON for IPC transmission
- Forwards data to the shell via the **`omarchy-shell notifications`** command

This design guarantees consistent handling across all scripts and applications integrated with Omarchy.

## IPC Routing to the Quickshell Daemon

Once `omarchy-notification-send` prepares the payload, it communicates with the running Quickshell process over the **Omarchy-shell IPC channel**. The command `omarchy-shell notifications …` transmits the JSON payload to the notification service component.

The receiving end is the **notification service QML component** found in `shell/plugins/notifications/Service.qml`. This file acts as the actual daemon that listens for incoming IPC commands, parses the JSON notification data, and manages notification lifecycle including creation, updates via `replaces_id`, and dismissal.

## Persistent Storage and History Management

The Omarchy notification system persists every notification as a one-line JSON file under **`~/.local/state/omarchy/notifications/`**. Each file is named after the notification's unique `id`, creating a durable record independent of the graphical interface.

When a user clicks or dismisses a notification, the corresponding JSON file is moved into **`notifications/history/`**, which provides two critical benefits.

- **DND resilience**: Silenced notifications remain accessible in the history directory even when the on-screen toast never appears
- **Crash recovery**: Notification state survives shell restarts and can be reconstructed from the filesystem

## Rendering and Do-Not-Disturb Logic in Service.qml

The **`Service.qml`** file in `shell/plugins/notifications/Service.qml` handles the visual representation and interaction logic. This Quickshell component reads the JSON files from the state directory and generates the visual toast notifications displayed to the user.

Key responsibilities of the QML service include:

- **Toast rendering**: Drawing notifications on screen with proper styling
- **Action handling**: Processing clicks, dismissals, and execution of attached commands
- **Replacement logic**: Handling `replaces_id` to update existing notifications rather than creating duplicates
- **DND enforcement**: Filtering notifications based on Do-Not-Disturb settings while still writing silenced messages to the history queue
- **Punch-through support**: Allowing a limited set of critical notifications to bypass DND when configured

## User-Facing Commands and Keyboard Shortcuts

Omarchy provides several CLI utilities for interacting with the notification system.

```bash

# Send a simple notification

omarchy-notification-send "Backup finished"

# Send with title and execute action on click

omarchy-notification-send "Download complete" "File ready" \
    --exec mpv -- "$HOME/Downloads/video.mkv"

# Wait for notification arrival with timeout

omarchy-notification-wait 10

# Dismiss notifications matching a pattern

omarchy-notification-dismiss "Error"

```

The system also provides global hotkeys for rapid interaction.

- **`Super + ,`**: Dismiss the current notification
- **`Super + Shift + ,`**: Silences or invokes the most recent notification

All these actions ultimately manipulate the JSON files in the state directory or send commands back through the IPC channel to `Service.qml`.

## Summary

- **Entry point**: All notifications must use **`bin/omarchy-notification-send`** rather than raw `notify-send` to ensure proper sanitization and IPC routing
- **IPC layer**: Messages travel via **`omarchy-shell notifications`** commands to the Quickshell process
- **Daemon**: **`shell/plugins/notifications/Service.qml`** receives JSON payloads, handles DND logic, and renders toasts
- **Storage**: Notifications persist as JSON files in **`~/.local/state/omarchy/notifications/`** and move to **`notifications/history/`** upon dismissal
- **Architecture**: The file-backed design ensures notification history survives DND suppression and shell restarts

## Frequently Asked Questions

### What is the difference between omarchy-notification-send and standard notify-send?

**`omarchy-notification-send`** is a mandatory wrapper that adds Omarchy-specific bookkeeping, respects DND settings, and routes messages through the shell's IPC system. Standard `notify-send` bypasses these controls; according to the Omarchy source code, internal code never uses raw `notify-send` directly.

### Where does Omarchy store notification history?

Notification histories are stored as one-line JSON files in **`~/.local/state/omarchy/notifications/history/`**. Active notifications live in the parent **`~/.local/state/omarchy/notifications/`** directory until dismissed or clicked.

### How does Do-Not-Disturb mode affect notification routing?

When DND is active, the QML daemon in **`Service.qml`** suppresses the visual toast but still writes the notification JSON to the history directory. This ensures you never miss critical alerts while maintaining a distraction-free environment. Certain "punch-through" notifications can bypass DND when explicitly configured.

### Can I use standard notify-send commands in Omarchy?

While the underlying system may intercept `notify-send` calls, you should always use **`omarchy-notification-send`** for compatibility. The wrapper ensures proper JSON formatting, IPC channel routing, and DND compliance that raw `notify-send` cannot provide.