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

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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}