Omarchy Hardware Detection Patterns: Shell-Based System Identification

Omarchy detects hardware through modular shell scripts in default/omarchy/ that use standard Linux utilities like lspci and lsusb, returning exit code 0 when components are found and non-zero otherwise.

The omaccom/omarchy repository implements hardware detection via lightweight, standalone bash scripts that probe system interfaces without external dependencies. These detection patterns enable the window manager to adapt menus, keybindings, and services dynamically based on the actual hardware present. Each script follows a consistent contract: probe standard Linux utilities, evaluate output for specific identifiers, and exit with a boolean status that higher-level helpers consume.

Core Detection Architecture

Omarchy's hardware detection relies on a simple but robust pattern implemented across shell scripts prefixed with hw- in the default/omarchy/ directory. According to the source code, each script functions as an independent detector that returns 0 (success) when the target hardware is present and non-zero when absent.

Standard Utilities and Interfaces

The detection scripts query several standard Linux interfaces to remain portable across Arch-based systems:

• lspci – Enumerates PCI devices including GPUs and audio controllers
• lsusb – Identifies USB peripherals like fingerprint readers
• /sys/class/dmi/id/ – Reads BIOS/DMI data for system model identification
• lsmod – Verifies kernel module loading status
• xrandr and /sys/class/drm/ – Detects display outputs and connection states

Hardware-Specific Detection Scripts

The repository contains targeted detection logic for common laptop and desktop components. Each script encapsulates the probing logic for a specific hardware category.

NVIDIA GPU Detection

The default/omarchy/hw-nvidia.sh script identifies discrete NVIDIA graphics cards by parsing lspci -nn output. It searches for the vendor ID 10de (NVIDIA Corporation) within VGA compatible controller entries.

# Detection logic from hw-nvidia.sh

lspci -nn | grep -i 'VGA compatible controller' | grep -q '10de'

Hybrid GPU (Optimus) Configuration

default/omarchy/hw-hybrid-gpu.sh detects Optimus-capable systems by combining the NVIDIA GPU check with a probe for Intel integrated graphics. It verifies the presence of the i915 kernel module alongside the NVIDIA detection.

# Combines NVIDIA detection with Intel driver check

hw-nvidia.sh && lsmod | grep -q '^i915'

ASUS ROG Laptop Identification

In default/omarchy/hw-asus-rog.sh, the system identifies ASUS Republic of Gamers laptops by reading /sys/class/dmi/id/product_name for case-insensitive "ROG" strings and confirming the asus-wmi kernel module is loaded.

# Checks DMI product name and kernel module

grep -qi 'rog' /sys/class/dmi/id/product_name && lsmod | grep -q 'asus-wmi'

Fingerprint Reader Support

The default/omarchy/hw-fingerprint.sh script queries USB devices for known fingerprint reader vendor IDs, specifically checking for 138a (Validity Sensors) among others. It falls back to parsing dmesg output for fingerprint-related kernel messages if USB enumeration is inconclusive.

# Primary check via lsusb

lsusb | grep -q '138a'

External Monitor Detection

default/omarchy/hw-external-monitors.sh determines whether external displays are connected by analyzing xrandr --query output. It counts display outputs marked as "connected" excluding the primary internal panel, returning success when at least one external monitor is active.

# Parses xrandr for connected outputs beyond the primary

xrandr --query | grep -c ' connected ' | grep -q '[2-9]'

Display Capability Probing

The default/omarchy/hw-display.sh script reads from /sys/class/drm/*/status and /sys/class/graphics/fb0/modes to determine supported resolutions, refresh rates, and HDR capability flags available to the system.

Integration with Omarchy Helpers

Omarchy exposes these detection patterns through wrapper functions that simplify conditional configuration. The omarchy-hw-present command invokes the corresponding hw-*.sh script and evaluates its exit status, allowing clean integration in shell scripts and JSON configuration files.

Conditional Configuration Examples

Use the detection patterns to branch system setup logic based on hardware availability:

# Enable ROG-specific RGB controls only on compatible hardware

if omarchy-hw-present asus-rog; then
    echo "Configuring ASUS ROG keyboard backlight"
    # Load asus-rog-specific daemon settings

else
    echo "Standard laptop configuration applied"
fi

# Select graphics driver based on GPU configuration

if omarchy-hw-present hybrid-gpu; then
    sudo systemctl enable optimus-manager.service
elif omarchy-hw-present nvidia; then
    sudo systemctl enable nvidia-persistenced.service
fi

Direct Script Invocation

For debugging or manual verification, invoke detection scripts directly and check the exit code:

/usr/share/omarchy/default/omarchy/hw-fingerprint.sh && \
    echo "Fingerprint reader available" || \
    echo "No fingerprint hardware detected"

Summary

Omarchy's hardware detection patterns provide a maintainable, extensible approach to system component identification:

• Exit-code contract enables simple Boolean logic where 0 indicates hardware presence and non-zero indicates absence
• Standard utility reliance uses ubiquitous Linux tools (lspci, lsusb, cat, grep) without requiring additional packages
• Modular script organization isolates detection logic in discrete hw-*.sh files under default/omarchy/
• Multi-layered verification combines PCI IDs, USB vendor codes, DMI strings, and kernel module checks for accuracy
• Helper integration exposes detection results via omarchy-hw-present for use throughout the configuration system

Frequently Asked Questions

How does Omarchy detect if a system has an NVIDIA GPU?

Omarchy executes default/omarchy/hw-nvidia.sh, which runs lspci -nn and searches the output for the vendor ID 10de within VGA compatible controllers. The script exits with status 0 if an NVIDIA GPU is detected, allowing the system to conditionally load proprietary drivers or power management settings.

Where are the hardware detection scripts located in the Omarchy repository?

According to the omaccom/omarchy source code, hardware detection scripts reside in the default/omarchy/ directory and follow the naming convention hw-<component>.sh. These files are installed to /usr/share/omarchy/default/omarchy/ on target systems.

Can I add custom hardware detection to Omarchy?

Yes. Create a new shell script named hw-<your-device>.sh in default/omarchy/ that probes for your specific hardware using standard utilities and exits with 0 when detected. The omarchy-hw-present helper automatically discovers scripts matching the hw-*.sh pattern, making your detection logic immediately available to the rest of the system.

What prevents false positives in Omarchy's hardware detection?

Each detection script implements specific filtering criteria—such as requiring both vendor ID matches and loaded kernel modules—to reduce false positives. For example, the ASUS ROG detection requires both "ROG" in the DMI product name and the asus-wmi module to be loaded, ensuring the script does not trigger on systems with merely similar naming conventions.

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