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

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.

[[ $(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

Generic Pattern Matching

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

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

PCI Device Inspection

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

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

External Monitor Detection

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

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

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:

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

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

# Example 1 – Detect an Asus ROG machine

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

# Example 2 – Generic product-name match

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

Capturing Device Names

# 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

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

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