How Omarchy Notifies Users About Pending Migrations: Systemd Service and Desktop Alerts Explained

Omarchy uses a systemd user service called omarchy-migrate-notify.service that executes at every graphical login, runs omarchy-migrate --pending to detect outstanding migrations, and displays a desktop notification with a clickable action when updates are waiting.

The omacum/omarchy repository implements a seamless notification system for pending system migrations through a combination of systemd user units and command-line utilities. This architecture ensures users are promptly informed about required updates without manual polling, while respecting system locks during active update operations.

The Systemd User Service Architecture

Omarchy leverages a user-level systemd service to trigger migration checks automatically. The unit file default/systemd/user/omarchy-migrate-notify.service defines an ExecStart command that invokes the /usr/bin/omarchy-migrate-notify helper script immediately upon login.

During initial system provisioning, the omarchy-provision-first-run script enables this service for all users, ensuring the notification mechanism survives reboots. The service is designed to restart intelligently, waiting for the global update lock to clear before presenting notifications to avoid interrupting ongoing system operations.

How Pending Migrations Are Detected

At the core of the notification system lies the omarchy-migrate --pending command. When executed by the notifier script, this command returns a non-zero exit status only when there are outstanding migrations waiting to be applied to the current user environment.

The detection flow works as follows:

1. The systemd unit triggers omarchy-migrate-notify
2. The script internally calls omarchy-migrate --pending
3. If the command succeeds (indicating pending migrations), the notification is constructed
4. If no migrations are pending, the script exits silently without displaying UI elements

This approach ensures that users receive notifications only when actionable work is required, minimizing notification fatigue.

Notification Delivery and Content

Desktop Notification Format

When pending migrations are detected, Omarchy constructs a desktop notification using its internal notification helper (avoiding raw notify-send calls). The notification includes:

• Title: "Pending Omarchy Migrations"
• Body: "Click to run X pending migration(s)." (where X represents the count)
• Icon: The large-slot glyph  (U+F021) for visual consistency with system update indicators

The notification payload includes a clickable action that allows users to launch the migration process directly from the desktop alert.

Lock-Aware Behavior

The notification system respects the omarchy-update.lock file to prevent UI spam during active system updates. When this lock is present, the notifier suppresses all migration alerts and enters a wait state. Once the lock releases—indicating the system update has completed—the service resumes and delivers any queued notifications.

This lock-handling logic is verified in the test suite located at test/shell.d/migrate-notify-test.sh, which validates that notifications are deferred during locked periods and delivered immediately after lock release.

Manual Invocation and Compatibility

You can trigger the notification workflow manually for testing or scripting purposes:

# Manually run the notifier to check for and display pending migrations

omarchy-migrate-notify

# Check migration status silently (returns non-zero if pending)

if ! omarchy-migrate --pending; then
    echo "Migrations are available"
fi

# Inspect the systemd service configuration

systemctl --user cat omarchy-migrate-notify.service

For backward compatibility with legacy tooling, Omarchy provides the omarchy-update-user-notify wrapper script located at bin/omarchy-update-user-notify. This hidden compatibility layer simply executes omarchy-migrate-notify, ensuring third-party scripts and aliases continue functioning while the underlying implementation has migrated to the new naming convention.

Summary

• Systemd Integration: Notifications are handled by omarchy-migrate-notify.service, enabled automatically during first-run provisioning via omarchy-provision-first-run.
• Detection Mechanism: The system checks for pending work using omarchy-migrate --pending, which returns a non-zero status only when migrations are required.
• Smart Delivery: Notifications respect the omarchy-update.lock file, suppressing alerts during active updates and resuming afterward to prevent interface conflicts.
• Notification Content: Users receive a desktop alert titled "Pending Omarchy Migrations" with a clickable action and icon glyph .
• Compatibility: The legacy omarchy-update-user-notify command remains available as a wrapper for the modern omarchy-migrate-notify implementation.

Frequently Asked Questions

What triggers the Omarchy migration notification?

The notification is triggered by the omarchy-migrate-notify.service systemd user unit executing at graphical login. This service runs the omarchy-migrate-notify script, which checks for pending migrations via omarchy-migrate --pending. When this command indicates outstanding migrations exist, the script generates a desktop notification with the title "Pending Omarchy Migrations."

How can I check for pending migrations manually without receiving a notification?

Execute omarchy-migrate --pending directly from your terminal. This command returns a non-zero exit code if migrations are pending, allowing you to check status in shell scripts without triggering the desktop notification UI. You can verify the result by running echo $? immediately after the command.

Why don't I see a notification during system updates?

Omarchy's notification system respects the global update lock file (omarchy-update.lock). When this lock is active—indicating a system update is in progress—the omarchy-migrate-notify service suppresses all migration alerts and waits for the lock to release. This design prevents notification spam and potential conflicts during active package operations.

Where can I customize the notification appearance or behavior?

Configuration is managed through the systemd unit file at default/systemd/user/omarchy-migrate-notify.service and the notification logic within bin/omarchy-migrate-notify. The icon glyph, title text, and body format are defined in the source code of the notification helper, while the service activation timing and restart policies are controlled via the systemd unit directives.

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