How Omarchy Menu Guards Control Visibility, Availability, and State

Omarchy menu guards are shell-script snippets defined in JSON-C configuration files that dynamically determine whether menu items are visible, dimmed, or checked by evaluating system conditions at runtime.

The basecamp/omarchy desktop environment implements a sophisticated declarative menu system where entries adapt to hardware capabilities and configuration state without requiring code changes. These Omarchy menu guards are defined directly in default/omarchy/omarchy-menu.jsonc and processed by the Quickshell runtime to generate context-sensitive interface elements.

The Three Types of Menu Guards

Omarchy supports three distinct guard fields that control different aspects of menu presentation. Each guard accepts a shell expression that is evaluated within the Quickshell environment whenever the menu is summoned.

The when Guard: Conditional Visibility

The when guard controls whether a menu row appears at all. The shell expression is evaluated as a condition test; if it exits with a non-zero status, the entire row is omitted from the generated menu tree.

This guard is ideal for hardware-specific features or configuration-dependent options. For example, the Suspend option only appears when the suspend-off toggle is not enabled:

"system.suspend": {
  "when": "! omarchy-toggle-enabled suspend-off",
  // ... other fields
}

According to the source code at line 38, this mechanism ensures users only see actions relevant to their current system capabilities.

The disabled Guard: Controlling Interactivity

The disabled guard keeps the menu row visible but renders it dimmed and prevents selection when the condition evaluates to true. Unlike when, which hides the item entirely, disabled provides visual feedback that an option exists but is currently unavailable.

This pattern appears frequently in installation workflows, where an entry should indicate "already installed" status:

"install.windows": {
  "disabled": "[[ -f $HOME/.local/share/applications/windows-vm.desktop ]]",
  // ... other fields
}

As implemented at line 111, this guard uses standard Bash test syntax ([[ ... ]]) to check for file existence before allowing the installation action.

The checked Guard: Displaying State

The checked guard appends a check-mark (✓) to the menu label when the condition evaluates to true. This allows toggle-style entries to reflect the current system state directly in the menu interface.

The touchpad haptics menu uses this to indicate the active setting:

"trigger.hardware.touchpad-haptics.low": {
  "checked": "[[ \"$(dell-xps-touchpad-haptics get)\" == \"low\" ]]",
  // ... other fields
}

Referencing line 79, this guard executes the external command to retrieve the current haptic level and compares it against the menu item's value.

Guard Evaluation Context and Syntax

All Omarchy menu guards are evaluated as shell-script snippets within the Quickshell environment. This design allows guards to leverage:

• Omarchy-specific helper commands such as omarchy-cmd-present, omarchy-hw-*, and omarchy-toggle-enabled
• Standard Bash test syntax including [[ ... ]] conditional expressions
• Environment variables and standard Unix utilities

Guards are reevaluated each time the menu is summoned, ensuring the UI always reflects the current system condition rather than stale cached values.

Practical Implementation Examples

Complete menu entries demonstrate how multiple guards combine to create sophisticated user interfaces:

// Hardware-specific entry that only appears on laptops
"trigger.hardware.laptop-display": {
  "icon": "󰛧",
  "label": "Laptop Display",
  "when": "omarchy-hw-laptop",
  "action": "omarchy-hyprland-monitor-internal toggle"
}

// Installation entry that becomes dimmed after completion
"install.browser.chrome": {
  "icon": "",
  "label": "Chrome",
  "disabled": "omarchy-pkg-present google-chrome",
  "action": "omarchy-launch-floating-terminal-with-presentation 'omarchy-install-browser chrome'"
}

// Multi-state toggle with visibility and checked guards
"trigger.hardware.touchpad-haptics.low": {
  "icon": "󰌌",
  "label": "Low",
  "when": "omarchy-hw-dell-xps-haptic-touchpad && omarchy-cmd-present dell-xps-touchpad-haptics",
  "checked": "[[ \"$(dell-xps-touchpad-haptics get)\" == \"low\" ]]",
  "action": "dell-xps-touchpad-haptics set low"
}

Key Source Files and Architecture

Understanding the guard system requires familiarity with three core components:

• default/omarchy/omarchy-menu.jsonc — The primary menu definition file containing all guard expressions and menu structure
• docs/menu.md — Human-readable documentation specifying the JSON-C schema and guard semantics
• shell/plugins/menu/Menu.qml — The Quickshell provider that parses the JSON-C definition and evaluates guard logic at runtime

These components work together to provide a declarative approach to menu state management, separating presentation logic from system detection mechanics.

Summary

• Omarchy menu guards are shell conditions defined in default/omarchy/omarchy-menu.jsonc that control menu item presentation
• The when guard hides items entirely when conditions evaluate to false (non-zero exit status)
• The disabled guard keeps items visible but dims them and prevents interaction when true
• The checked guard appends visual indicators to show active state or selection
• Guards execute within the Quickshell environment using standard Bash syntax and Omarchy helper commands
• All conditions are reevaluated dynamically each time the menu opens, ensuring real-time accuracy

Frequently Asked Questions

What happens if a guard command fails or returns an error?

When a shell guard returns a non-zero exit status, Omarchy treats the condition as false. For the when guard, this means the item is hidden; for disabled and checked, the guard condition evaluates as not met. The menu system handles exit codes gracefully without crashing the interface.

Can guards use custom scripts or only built-in Omarchy commands?

Guards may reference any executable available in the system PATH, including custom user scripts, standard Unix utilities, and Omarchy-specific helpers. The evaluation context uses the user's shell environment, so complex logic can be wrapped in external scripts and called from the guard expression.

How do I troubleshoot why a menu item is not appearing?

Check the when guard condition by running the exact shell expression manually in a terminal. If the command exits with status 0, the item should appear. For hardware-dependent items, verify that helper commands like omarchy-hw-laptop or omarchy-cmd-present return the expected results and that the JSON-C syntax in omarchy-menu.jsonc is valid.

Is there a performance impact from evaluating guards every time the menu opens?

Because guards are lightweight shell tests (typically checking file existence, command presence, or reading simple configuration values), the evaluation overhead is negligible on modern systems. The Quickshell provider executes these conditions asynchronously where possible, ensuring menu responsiveness even with multiple guarded entries.

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