How Omarchy Detects Hardware: A Deep Dive Into Its Predicate-Based Detection System

Omarchy uses a collection of lightweight bash scripts named omarchy-hw-<name> that exit with status 0 when hardware is detected, enabling fast, dependency-free conditional logic across menus, install hooks, and shell plugins.

Omarchy's hardware detection system is built on a simple but powerful pattern: discrete, single-purpose executables that act as boolean predicates. This design keeps detection fast, portable, and integrable everywhere from JSONC menu definitions to QML plugins. Understanding how these detectors work is essential for customizing your Omarchy installation or contributing new hardware support.

The omarchy-hw-* Naming Convention

Every hardware detector in Omarchy follows a strict naming convention. Scripts reside in the bin/ directory and are prefixed with omarchy-hw-. This prefix signals to the CLI router, menu system, and other consumers that the script is a quiet predicate—it produces no output and communicates solely through exit codes.

This convention enables automatic discovery. The router in docs/cli-router.md recognizes these scripts as commands, and the Quickshell menu parser in default/omarchy/omarchy-menu.jsonc uses them directly in "when" conditions.

How Detection Works: The Three-Step Flow

Omarchy's hardware detection follows a predictable pipeline that keeps the system decoupled and testable.

Step 1: Kernel Filesystem Inspection

Each detector reads from /sys and /proc without invoking heavy external tools. This avoids waking suspended GPUs or introducing latency from parsing commands like lspci.

The omarchy-hw-asus-rog script exemplifies this approach. It checks two DMI fields exposed by the kernel:

• /sys/class/dmi/id/sys_vendor for the string "ASUS"
• /sys/class/dmi/id/product_family for the string "ROG"

If both match, the script exits 0. Any mismatch or missing file results in exit 1.

Step 2: Exit Code Evaluation

Callers interpret the exit code as a boolean. This works in any shell context without parsing output:

if omarchy-hw-asus-rog; then
    echo "Applying ASUS ROG-specific power profiles"
fi

Step 3: Conditional Action

The result propagates through Omarchy's subsystems. Menus show or hide entries. Install scripts apply vendor-specific fixes. Polkit agents adjust authentication behavior.

Key Detector Scripts

omarchy-hw-asus-rog — Vendor-Family Detection

This script demonstrates the canonical pattern for laptop and motherboard detection. It reads DMI strings directly, making no assumptions about device naming beyond what the firmware exposes.

Source: bin/omarchy-hw-asus-rog

Example usage in install hooks:

# From install/hardware/asus-rog.sh

omarchy-hw-asus-rog && {
    systemctl enable asus-fan-control
    modprobe asus_nb_wmi
}

omarchy-hw-match — Generic Pattern Matching

When specific hardware variants need targeting without dedicated scripts, omarchy-hw-match provides flexible DMI matching. It performs case-insensitive searches against both product_name and product_family fields.

Source: bin/omarchy-hw-match

Chaining for precise targeting:

# Target only ROG Z13 tablet models

omarchy-hw-asus-rog && omarchy-hw-match "GZ302" && {
    # Apply touchpad fix specific to Z13

    install/hardware/asus/fix-z13-touchpad.sh
}

omarchy-hw-nvidia — GPU Detection Without Power-On

GPUs in suspended states can hang or delay when probed. The NVIDIA detector avoids this by inspecting PCI sysfs entries without triggering device initialization. It supports an override environment variable for testing:

# Override PCI device discovery path for unit testing

OMARCHY_PCI_DEVICES_PATH=/custom/pci/path omarchy-hw-nvidia

Source: bin/omarchy-hw-nvidia

Safe detection in boot scripts:

# Early boot: check for NVIDIA without waking GPU

if omarchy-hw-nvidia; then
    echo "options nvidia-drm modeset=1" > /etc/modprobe.d/nvidia.conf
fi

Integration Points

Menu System (omarchy-menu.jsonc)

The Quickshell-based menu uses hardware predicates to conditionally render entries. The "when" field accepts any executable name; if it exits 0, the item appears.

Example from default/omarchy/omarchy-menu.jsonc:

{
    "label": "ROG Gaming Center",
    "exec": "rog-control-center",
    "when": "omarchy-hw-asus-rog"
}

Source: default/omarchy/omarchy-menu.jsonc

CLI Router

The router documented in docs/cli-router.md automatically groups omarchy-hw-* scripts under the hw command namespace. This provides a consistent interface for manual checks:

omarchy hw asus-rog    # Executes omarchy-hw-asus-rog

omarchy hw nvidia      # Executes omarchy-hw-nvidia

Source: [docs/cli-router.md](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md)

Polkit and QML Plugins

Shell plugins execute detectors directly. The Polkit agent in shell/plugins/polkit/PolkitAgent.qml checks laptop lid state:

// QML embedding of hardware predicate
property string lidState: {
    var result = exec("omarchy-hw-laptop-closed && echo closed || echo open");
    return result.stdout.trim();
}

Design Principles

• Zero dependencies beyond coreutils — cat, grep, and read suffice for all detection
• No output pollution — Exit codes only; redirect any debug output to stderr
• Environment overrides — Variables like OMARCHY_PCI_DEVICES_PATH enable testing
• Composability — Shell && and || chain detectors into complex conditions
• Speed — Typical execution completes in under 10ms

Summary

• Omarchy's hardware detection relies on omarchy-hw-* scripts that return exit code 0 for true conditions
• Detectors read from /sys/class/dmi/id and /sys/bus/pci without external command dependencies
• The omarchy-hw-asus-rog, omarchy-hw-match, and omarchy-hw-nvidia scripts cover common detection scenarios
• Integration spans JSONC menus, CLI routing, install hooks, and QML plugins through uniform exit-code contracts

Frequently Asked Questions

How do I add support for a new hardware type?

Create a new executable in bin/ named omarchy-hw-<yourname> that exits 0 when your hardware is detected. Follow the existing pattern of reading /sys/class/dmi/id for laptop/motherboard traits or /sys/bus/pci for device detection. No registration is required—the CLI router and menu system will discover it automatically.

Can I test hardware detection without the actual hardware?

Yes. Most detectors respect environment variables for stubbing paths. For PCI-based detection, set OMARCHY_PCI_DEVICES_PATH to a directory containing mock sysfs entries. For DMI-based detection, temporarily override the file paths in the script or use a container with bind-mounted test fixtures.

Why doesn't Omarchy use lshw or hwinfo for detection?

External hardware discovery tools introduce latency, dependencies, and side effects like GPU wake-on-probe. Omarchy's sysfs-only approach completes in milliseconds with no package requirements, making it safe for early boot, suspended systems, and embedded environments.

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