How to Add a New Hardware Detection Command (hw-* Prefix) in Omarchy

To add a new hardware detection command in Omarchy, create an executable bash script named omarchy-hw-<device> in the bin/ directory that returns exit code 0 when hardware is present and non-zero when absent, optionally using # omarchy:hidden=true to hide it from the help menu.

Omarchy’s hardware detection system uses a strict naming convention and automatic discovery mechanism to expose device checks through the CLI. Any executable script prefixed with omarchy-hw- in the repository’s bin/ folder is automatically recognized by the command router and integrated into the hardware section of the Omarchy menu without manual registration.

Understanding the Omarchy Hardware Command Convention

The hardware detection framework in omacom/omarchy follows a predictable pattern based on file naming, exit codes, and executable permissions. Commands must reside in the bin/ directory and follow the naming template omarchy-hw-<name>, where <name> describes the hardware component being detected.

The CLI routing logic inspects the bin/ directory for executables beginning with omarchy-. When a user runs omarchy hw-<name>, the system invokes the corresponding bin/omarchy-hw-<name> script. The command’s visibility in the interactive menu depends on a special metadata comment: adding # omarchy:hidden=true anywhere in the script hides it from the help menu, while omitting this line makes it appear automatically in the Hardware group.

Step-by-Step Implementation Guide

Create the Detection Script

Start by creating a new file in the bin/ directory using the required naming convention. The script must use #!/usr/bin/env bash as its shebang and be made executable immediately.

touch bin/omarchy-hw-mydevice
chmod +x bin/omarchy-hw-mydevice

Open the file and add a descriptive header comment explaining what hardware the command detects. This documentation aids both users and maintainers browsing the source code.

Implement Detection Logic and Exit Codes

The detection logic relies on exit codes to communicate hardware presence. Return exit code 0 when the hardware is detected, and any non-zero value when it is absent. Common detection methods include checking /sys or /dev entries, or using utilities like lspci, lsusb, or vulkaninfo.

#!/usr/bin/env bash

# omarchy-hw-mydevice

# Detects whether the proprietary MyDevice USB dongle is attached.

#

# Exit codes:

#   0 – device present

#   1 – device not present

if lsusb -d 1234:5678 >/dev/null 2>&1; then
    exit 0
else
    exit 1
fi

Add Metadata for Menu Visibility

Control whether your command appears in the Omarchy menu by adding or omitting the hidden metadata tag. To hide the command from the help menu while keeping it callable via CLI, include:

# omarchy:hidden=true

Place this comment anywhere in the script, typically near the top with other metadata. If you want users to discover the command through the interactive menu, leave this line out entirely.

Write Automated Tests

Every hardware command should have a corresponding test in test/shell.d/. Create a test script named hw-<name>-test.sh that sources the base test framework and asserts the expected exit status.

#!/usr/bin/env bash

# SPDX-License-Identifier: MIT

# Test for omarchy-hw-mydevice

source "$(dirname "$0")/base-test.sh"

omarchy hw-mydevice
status=$?

assert_eq "$status" 0 "mydevice should be detected"

Make the test executable and run the full suite with ./test/shell to verify integration.

Complete Code Examples

Sample Hardware Detection Script

Here is a complete reference implementation for detecting a USB webcam, following the pattern used in bin/omarchy-hw-webcam:

#!/usr/bin/env bash

# omarchy-hw-webcam

# Detects whether a video4linux webcam is present.

#

# Exit codes:

#   0 – webcam found

#   1 – no webcam detected

[[ -e /dev/video0 ]] && exit 0 || exit 1

Sample Test Implementation

Corresponding test file at test/shell.d/hw-webcam-test.sh:

#!/usr/bin/env bash

# SPDX-License-Identifier: MIT

# Test for omarchy-hw-webcam

source "$(dirname "$0")/base-test.sh"

omarchy hw-webcam
status=$?

assert_eq "$status" 0 "Webcam should be present in test environment"

Adding the Script to the Repository

Use the following commands to stage and commit your new hardware detection command:

git add bin/omarchy-hw-mydevice
git add test/shell.d/hw-mydevice-test.sh
git commit -m "Add hardware detection for MyDevice USB dongle"

Integration and Testing

Once placed in bin/ with executable permissions, the new command integrates automatically. The Omarchy menu system scans for omarchy-hw-* patterns during initialization, populating the Hardware group with any non-hidden commands. No manual menu configuration is required in docs/menu.md or elsewhere.

Run the shell test suite to confirm your implementation does not break existing detections:

./test/shell

The test harness will execute hw-mydevice-test.sh and report any assertion failures or integration errors.

Key Files and References

• bin/omarchy-hw-webcam – Reference implementation for video device detection
• bin/omarchy-hw-vulkan – Reference implementation for GPU driver detection using Vulkan utilities
• test/shell.d/hw-webcam-test.sh – Example test harness showing assertion patterns for hardware commands
• docs/menu.md – Documentation describing how commands are exposed in the Omarchy menu system
• agents/skills/command-metadata.md – Guidelines for command script metadata and naming conventions

Summary

• Naming: Use bin/omarchy-hw-<name> for all hardware detection scripts

• Permissions: Ensure files are executable (chmod +x) for discovery to work

• Exit Codes: Return 0 for hardware present, non-zero for absent

• Visibility: Add # omarchy:hidden=true to hide commands from the menu

• Testing: Create corresponding tests in test/shell.d/hw-<name>-test.sh

• Discovery: Commands appear automatically in the Hardware group; no manual registration needed

Frequently Asked Questions

What exit code should my hardware detection command return?

Return exit code 0 when the hardware is detected and any non-zero integer (typically 1) when it is not present. Omarchy’s CLI interprets zero as success (hardware available) and non-zero as failure (hardware unavailable).

Can I use any programming language for the detection script?

While the examples use bash, any executable script will work provided it follows the omarchy-hw-<name> naming convention, has proper execute permissions, and returns the correct exit codes. However, the existing codebase uses bash consistently for hardware detection.

How do I hide a hardware command from the interactive menu?

Add the comment # omarchy:hidden=true anywhere in the script. This metadata tag prevents the command from appearing in the Omarchy help menu while keeping it callable directly via omarchy hw-<name>.

Where should I place tests for my new hardware command?

Create a test file named hw-<name>-test.sh in the test/shell.d/ directory. Source base-test.sh and use assertions to verify exit codes, following the pattern established in test/shell.d/hw-webcam-test.sh.

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