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

> Learn how omarchy-menu.jsonc conditionally renders menu entries using shell conditions with when checked and disabled fields. Explore exit codes and test expressions.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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:

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

```

*(source: [`omarchy-menu.jsonc#L38`](https://github.com/omacom/omarchy/blob/main/default/omarchy/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:

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

```

*(source: [`omarchy-menu.jsonc#L74`](https://github.com/omacom/omarchy/blob/main/default/omarchy/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":

```json
"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`](https://github.com/omacom/omarchy/blob/main/default/omarchy/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:

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

```

*(source: [`omarchy-menu.jsonc#L51`](https://github.com/omacom/omarchy/blob/main/default/omarchy/omarchy-menu.jsonc#L51))*

### Example: DNS Configuration

Similarly, DNS provider entries check against the active configuration:

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

```

*(source: [`omarchy-menu.jsonc#L32`](https://github.com/omacom/omarchy/blob/main/default/omarchy/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:

```json
"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`](https://github.com/omacom/omarchy/blob/main/default/omarchy/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/docs/menu.md). The QML evaluation logic is implemented in `shell/plugins/menu/Menu.qml`.