# How Omarchy Hardware Detection Commands Work: A Deep Dive into Sysfs-Based Detection

> Explore how Omarchy hardware detection commands use Bash scripts to interrogate sysfs and DMI data for hardware identification. Discover efficient system analysis.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-18

---

**Omarchy hardware detection commands are lightweight Bash scripts in the `bin/` directory that interrogate Linux sysfs and DMI data to identify hardware components, returning exit code 0 for matches and optionally printing values to stdout.**

The Omarchy project implements a unique approach to hardware detection that prioritizes speed, reliability, and testability over traditional tool-based methods. This article examines how these detection helpers operate, their design conventions, and practical usage patterns based on the source code in `basecamp/omarchy`.

## Core Design Conventions

Every Omarchy hardware detection script follows a standardized structure to ensure consistency across the toolchain.

### Required Script Elements

- **`#!/bin/bash` header** — Guarantees execution with Bash 5
- **`# omarchy:summary=…` comment** — Provides human-readable descriptions for the command-metadata system

- **Exit status semantics** — `0` indicates hardware match or true condition; `1` indicates no match
- **Stdout output** — Scripts that return values (like device names) print to stdout and exit 0

### Optional Metadata

- **`# omarchy:hidden=true`** — Marks internal helpers that run but remain hidden from user-visible listings

### Environment-Based Testing

Variables such as `OMARCHY_DRM_PATH`, `OMARCHY_PCI_DEVICES_PATH`, and `OMARCHY_BACKLIGHT_PATH` enable injection of mock sysfs locations. This design makes the entire detection suite testable without requiring actual hardware.

## Hardware Detection Patterns

The Omarchy hardware detection commands avoid heavyweight tools, reading directly from kernel-exposed interfaces.

### DMI-Based Vendor and Product Detection

Scripts read DMI files under `/sys/class/dmi/id/` to identify specific manufacturers and product families.

```bash
[[ $(cat /sys/class/dmi/id/sys_vendor) == "ASUSTeK COMPUTER INC." ]] &&
    grep -q "ROG" /sys/class/dmi/id/product_family   # omarchy-hw-asus-rog

```

Source: [`bin/omarchy-hw-asus-rog`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-hw-asus-rog)

### Generic Pattern Matching

The `omarchy-hw-match` helper provides flexible, case-insensitive detection against product names or families:

```bash
grep -qi "$1" /sys/class/dmi/id/product_name 2>/dev/null ||
grep -qi "$1" /sys/class/dmi/id/product_family 2>/dev/null

```

Source: [`bin/omarchy-hw-match`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-hw-match)

### PCI Device Inspection

Rather than parsing `lspci` output, scripts examine raw sysfs entries under `/sys/bus/pci/devices` for vendor, class, and device identifiers:

```bash
for device in "$pci_devices_path"/*; do
    [[ $(< "$device/vendor") == "0x10de" ]] || continue   # NVIDIA vendor

    [[ $(< "$device/class") == 0x03* ]] || continue      # Display controller class

    (( $(< "$device/device") >= 0x1e00 )) && exit 0       # GSP firmware check

done
exit 1

```

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

### External Monitor Detection

The `omarchy-hw-external-monitors` command enumerates DRM connector status files while excluding internal panel types:

```bash
for status in "$drm_path"/card*-*/status; do
    [[ -e $status ]] || continue
    [[ $status =~ -(eDP|LVDS|DSI)-[^/]+/status$ ]] && continue
    [[ $(< $status) == "connected" ]] && exit 0
done
exit 1

```

Source: [`bin/omarchy-hw-external-monitors`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-hw-external-monitors)

This pattern filters out `eDP`, `LVDS`, and `DSI` connectors to identify only externally attached displays.

### Display Backlight Selection

The `omarchy-hw-display` command implements a heuristic priority system for identifying the correct backlight control device:

```bash
device="$(ls -1 "$backlight_path" 2>/dev/null | grep -vx appletb_backlight | head -n1)"
for candidate in "$backlight_path"/gmux_backlight "$backlight_path"/amdgpu_bl* \
                 "$backlight_path"/intel_backlight "$backlight_path"/acpi_video*; do
    if [[ -e $candidate ]]; then
        device="${candidate##*/}"
        break
    fi
done
printf '%s\n' "$device"

```

Source: [`bin/omarchy-hw-display`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-hw-display)

The priority order favors `gmux_backlight` (Apple hybrid GPUs), AMD GPU backlights, Intel backlights, and finally ACPI video devices.

## Practical Usage Examples

### Detecting Specific Hardware Classes

```bash

# Example 1 – Detect an Asus ROG machine

if omarchy-hw-asus-rog; then
    echo "Running on an Asus ROG laptop"
fi

```

```bash

# Example 2 – Generic product-name match

if omarchy-hw-match "Surface"; then
    echo "Surface hardware detected"
fi

```

### Capturing Device Names

```bash

# Example 3 – Get the backlight device name for brightness control

display_device=$(omarchy-hw-display) || exit 1
echo "Backlight device: $display_device"

```

### Conditional Configuration Scripts

```bash

# Example 4 – Conditional logic in a setup script

if omarchy-hw-nvidia-gsp; then
    echo "Enabling GSP-aware NVIDIA configuration"
fi

```

## Key Detection Scripts Reference

| Script | Purpose | Detection Method |
|--------|---------|------------------|
| `bin/omarchy-hw-asus-rog` | Asus ROG laptops | DMI vendor + family strings |
| `bin/omarchy-hw-match` | Generic pattern matching | Case-insensitive DMI grep |
| `bin/omarchy-hw-nvidia-gsp` | NVIDIA GSP firmware GPUs | PCI vendor/class/device sysfs |
| `bin/omarchy-hw-external-monitors` | External display presence | DRM connector status files |
| `bin/omarchy-hw-display` | Backlight device selection | Prioritized sysfs enumeration |
| `bin/omarchy-hw-clamshell` | Laptop docked mode | Composite lid + external check |
| `bin/omarchy-hw-fingerprint` | Fingerprint reader presence | USB sysfs inspection |
| `bin/omarchy-hw-dell-xps-oled` | Dell XPS OLED models | `omarchy-hw-match` wrapper |

## Architecture Benefits

The Omarchy hardware detection approach provides several advantages over traditional detection methods:

- **Speed** — Direct sysfs reads eliminate subprocess overhead from tools like `lspci`, `xrandr`, or `dmidecode`
- **Reliability** — Kernel interfaces are stable and available early in boot sequences
- **Testability** — Environment variable overrides enable complete mocking without hardware dependencies
- **Portability** — Pure Bash with no external dependencies beyond standard sysfs paths
- **Composability** — Exit-code-based design allows easy chaining with shell logical operators

These helpers function as **pure functions**: they inspect system state, optionally emit values, and delegate action to calling scripts based on exit codes. This separation of detection from policy enables higher-level commands like `omarchy-apply-hardware` and `omarchy-toggle-input-device` to make hardware-aware decisions through reliable, fast introspection.

## Summary

- Omarchy hardware detection commands reside in `bin/` as small Bash scripts following strict conventions
- Detection relies exclusively on Linux sysfs and DMI interfaces, avoiding external tool dependencies
- Exit codes communicate match status (`0` = match, `1` = no match) with optional stdout values
- Environment variables enable full testability through path injection
- Common patterns include DMI string matching, PCI device enumeration, DRM connector status checks, and prioritized backlight selection

## Frequently Asked Questions

### How does Omarchy detect hardware without using standard tools like lspci or dmidecode?

Omarchy hardware detection commands read directly from kernel-exposed sysfs interfaces. For PCI devices, scripts examine `/sys/bus/pci/devices/*/vendor`, `class`, and `device` files. For system identification, they parse `/sys/class/dmi/id/` files containing vendor, product name, and family strings. This approach eliminates subprocess overhead and removes dependencies on user-space utilities that may not be available in all environments.

### Can Omarchy hardware detection be tested without actual hardware?

Yes. The detection scripts accept environment variable overrides such as `OMARCHY_DRM_PATH`, `OMARCHY_PCI_DEVICES_PATH`, and `OMARCHY_BACKLIGHT_PATH`. These variables allow test suites to provide mock sysfs directory structures, enabling full verification of detection logic without physical hardware present.

### What is the difference between omarchy-hw-match and vendor-specific scripts like omarchy-hw-asus-rog?

`omarchy-hw-match` is a generic, reusable helper that performs case-insensitive pattern matching against DMI product name and family fields. Vendor-specific scripts like `omarchy-hw-asus-rog` encode precise detection logic for particular hardware classes, combining multiple DMI checks for accuracy. The generic helper enables quick prototyping and one-off checks, while dedicated scripts provide rigorous identification for hardware requiring special handling.

### How does Omarchy determine which backlight device to control?

The `omarchy-hw-display` command implements a prioritized search through known backlight class entries. It excludes `appletb_backlight` (Apple Touch Bar), then searches in order: `gmux_backlight` for Apple hybrid graphics, `amdgpu_bl*` for AMD GPUs, `intel_backlight` for Intel integrated graphics, and finally `acpi_video*` as fallback. The first match becomes the selected device, returned via stdout.