How omarchy-menu.jsonc Defines Menu Entries with Shell Conditions

The omarchy-menu.jsonc file uses three optional fields—when, checked, and disabled—to conditionally render menu entries based on shell command exit codes and test expressions.

omarchy-menu.jsonc is a JSONC configuration file that powers the Omarchy desktop menu hierarchy. Located at default/omarchy/omarchy-menu.jsonc, it maps entry IDs to objects containing display properties and optional shell conditions. These conditions let the menu adapt dynamically to hardware capabilities, installed software, and user preferences without requiring procedural code changes.

The Three Shell Condition Fields

Omarchy supports three fields for conditional menu rendering. Each accepts a shell command or test expression that is evaluated when the menu is built.

Field	Behavior	Shell Exit Code Interpretation
when	Show or hide the entire entry	Entry omitted if command returns non-zero
checked	Display a checkmark (✓) beside the label	Checkmark shown if command returns zero
disabled	Dim the entry and prevent selection	Entry dimmed if command returns zero

These fields are documented in the file header at lines 16–20 of default/omarchy/omarchy-menu.jsonc.

How the when Field Controls Visibility

The when field determines whether an entry appears at all. This is useful for hardware-specific or toggle-dependent options.

Example: Conditional Sleep Entry

The system.suspend entry only appears when the suspend-off toggle is disabled:

"system.suspend": {
  "icon": "󰒲",
  "label": "Suspend",
  "when": "! omarchy-toggle-enabled suspend-off",
  "action": "systemctl suspend"
}

(source: omarchy-menu.jsonc#L38)

The ! negates the exit code of omarchy-toggle-enabled suspend-off. If the toggle is enabled (command returns 0), the ! makes the expression fail, and the entry is hidden.

Example: Laptop-Only Hardware Options

Display settings for laptop hardware use omarchy-hw-laptop to gate visibility:

"trigger.hardware.laptop-display": {
  "icon": "󰛧",
  "label": "Laptop Display",
  "when": "omarchy-hw-laptop",
  "action": "omarchy-hyprland-monitor-internal toggle"
}

(source: omarchy-menu.jsonc#L74)

How the checked Field Adds Checkmarks

The checked field marks an entry when its condition evaluates true, typically indicating a current setting or active configuration.

Example: Dell XPS Haptic Touchpad Level

This entry shows a checkmark when the haptic level is set to "low":

"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"
}

(source: omarchy-menu.jsonc#L79)

Note the combination: when ensures the hardware exists and the command is installed, while checked reflects the runtime state.

Example: Default Browser Selection

Menu entries for default browsers use checked to highlight the current selection:

"setup.default.browser.chromium": {
  "icon": "",
  "label": "Chromium",
  "checked": "[[ \"$(omarchy-default-browser)\" == \"chromium\" ]]",
  "action": "omarchy-default-browser chromium"
}

(source: omarchy-menu.jsonc#L51)

Example: DNS Configuration

Similarly, DNS provider entries check against the active configuration:

"setup.network.dns.cloudflare": {
  "icon": "󰅟",
  "label": "Cloudflare",
  "checked": "[[ \"$(omarchy-dns)\" == \"Cloudflare\" ]]",
  "action": "omarchy-dns Cloudflare"
}

(source: omarchy-menu.jsonc#L32)

How the disabled Field Dims Unavailable Entries

Unlike when, which hides entries entirely, disabled keeps them visible but inactive—useful for showing installed or completed states.

Example: Windows VM Installation

The Windows installation option dims when the VM desktop file already exists:

"install.windows": {
  "icon": "󰍲",
  "label": "Windows",
  "disabled": "[[ -f $HOME/.local/share/applications/windows-vm.desktop ]]",
  "action": "omarchy-launch-floating-terminal-with-presentation 'omarchy-windows-vm install'"
}

(source: omarchy-menu.jsonc#L14)

The [[ -f ... ]] test checks file existence. When true, the entry remains visible but cannot be selected.

Shell Environment and Helper Commands

Conditions in omarchy-menu.jsonc execute in the Omarchy shell environment, which provides several helper commands:

• omarchy-toggle-enabled <name> — Check if a named toggle is active
• omarchy-hw-laptop — Succeed if running on laptop hardware
• omarchy-hw-dell-xps-haptic-touchpad — Detect specific Dell XPS hardware
• omarchy-cmd-present <command> — Verify command availability in $PATH
• omarchy-default-browser — Return the currently configured default browser
• omarchy-dns — Return the active DNS provider

These utilities keep menu conditions readable and maintainable without inline shell complexity.

Runtime Evaluation in Menu.qml

The shell conditions are not parsed statically. The file shell/plugins/menu/Menu.qml implements the QML provider that:

1. Reads omarchy-menu.jsonc at menu launch
2. Executes each when, checked, and disabled expression in a subshell
3. Constructs the final menu tree based on exit codes

This evaluation happens every time the menu opens, ensuring state changes (toggles, hardware events, configuration updates) reflect immediately without restarting the session.

Supported Shell Expression Patterns

Based on patterns in the source file, valid when/checked/disabled values include:

Pattern Type	Example	Use Case
Simple command	"omarchy-hw-laptop"	Hardware detection
Negation	"! omarchy-toggle-enabled suspend-off"	Inverted toggle check
Command substitution	"[[ \"$(omarchy-dns)\" == \"Cloudflare\" ]]"	Value comparison
File test	"[[ -f $HOME/.local/share/applications/windows-vm.desktop ]]"	Installation state
Logical AND	"omarchy-hw-dell-xps-haptic-touchpad && omarchy-cmd-present dell-xps-touchpad-haptics"	Compound conditions

Summary

• when in omarchy-menu.jsonc controls entry visibility based on shell exit codes
• checked adds visual checkmarks when conditions evaluate true
• disabled dims entries without hiding them, indicating unavailable states
• Conditions reference Omarchy helper commands like omarchy-toggle-enabled and omarchy-default-browser
• The QML provider at shell/plugins/menu/Menu.qml evaluates expressions at menu runtime
• File location: default/omarchy/omarchy-menu.jsonc (definition), docs/menu.md (schema documentation)

Frequently Asked Questions

Can I use arbitrary shell commands in omarchy-menu.jsonc conditions?

Yes. The when, checked, and disabled fields accept any valid shell expression. The Menu.qml provider executes them in a subshell and interprets the exit code. You can use compound tests, command substitution, variables, and logical operators—though for maintainability, the codebase prefers Omarchy's helper commands.

How do I debug why a menu entry isn't appearing?

Check the when condition directly in your terminal. Run the same expression and inspect the exit code with echo $?. A non-zero exit suppresses the entry. Also verify that required helper commands like omarchy-hw-laptop or omarchy-toggle-enabled are in your $PATH.

What's the difference between when and disabled?

when removes the entry entirely when its condition fails. disabled keeps the entry visible but grays it out and prevents selection. Use when for irrelevant options (hardware-specific features on incompatible systems). Use disabled for temporarily unavailable actions (already-installed software, missing prerequisites).

Where are the condition fields documented in the repository?

The schema documentation appears at the top of default/omarchy/omarchy-menu.jsonc (lines 16–20) and is expanded in docs/menu.md. The QML evaluation logic is implemented in shell/plugins/menu/Menu.qml.

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