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

> Discover how Omarchy detects hardware using a predicate-based system of lightweight bash scripts. Learn about its fast, dependency-free detection for menus, hooks, and plugins.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-05

---

**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`](https://github.com/omacom/omarchy/blob/main/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:

```bash
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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-hw-asus-rog)

**Example usage in install hooks:**

```bash

# 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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-hw-match)

**Chaining for precise targeting:**

```bash

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

```bash

# Override PCI device discovery path for unit testing

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

```

**Source:** [`bin/omarchy-hw-nvidia`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-hw-nvidia)

**Safe detection in boot scripts:**

```bash

# 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`:**

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

```

**Source:** [`default/omarchy/omarchy-menu.jsonc`](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc)

### CLI Router

The router documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) automatically groups `omarchy-hw-*` scripts under the `hw` command namespace. This provides a consistent interface for manual checks:

```bash
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/main/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
// 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.