# How the Omarchy Menu Is Defined: Complete Guide to JSON-C Configuration and Dynamic Providers

> Learn how the Omarchy menu is defined using a single JSON-C config file. Explore properties like icon, label, action, and dynamic providers to customize your menu.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-08-31

---

**The Omarchy menu is defined in a single JSON‑C configuration file at `default/omarchy/omarchy-menu.jsonc`, which declares hierarchical menu entries with properties like `icon`, `label`, `action`, `provider`, `when`, and `checked` to control appearance, behavior, and dynamic content.**

The Omarchy menu system powers the graphical launcher in the [omacom/omarchy](https://github.com/omacom/omarchy) open‑source project. Rather than hard‑coding menu items in compiled source, Omarchy uses a declarative JSON‑C file that the shell parses at runtime. This approach lets users customize the entire menu hierarchy without rebuilding the project.

---

## Where the Omarchy Menu Definition Lives

The canonical definition resides in one file:

- **`default/omarchy/omarchy-menu.jsonc`** — Core static menu definition ([source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc))

This file is loaded on every shell startup. Because it uses **JSON‑C** (JSON with comments), you can annotate entries and reload changes instantly without compilation.

---

## Anatomy of a Menu Entry

Each entry in `omarchy-menu.jsonc` is an object with the following properties:

| Property | Type | Purpose |
|----------|------|---------|
| `icon` | string | Unicode glyph displayed in the UI (e.g., `󰀻`) |
| `label` | string | Human‑readable name shown in the menu |
| `aliases` *(optional)* | array | Alternate command names that resolve to the same entry |
| `action` *(optional)* | string | Shell command executed when the item is selected |
| `provider` *(optional)* | string | Name of a provider module that supplies sub‑items dynamically |
| `when` *(optional)* | string | Bash condition that must evaluate to true for the item to appear |
| `checked` *(optional)* | string | Bash expression indicating a toggled state (checkbox) |

Dot‑notation in keys creates nested sub‑menus. For example, `learn.keybindings` renders as *Learn → Keybindings*.

---

## Top‑Level Menu Groups in Omarchy

Lines 24‑33 of `omarchy-menu.jsonc` establish the main sections ([source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L24-L33)):

- **apps** — Application launcher with dynamic provider
- **learn** — Documentation and keybinding helpers (lines 45‑53, [source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L45-L53))
- **trigger** — Quick utilities: emoji picker, screenshots, hardware toggles (lines 56‑73, [source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L56-L73))
- **style** — Theme, background, and bar customization (lines 104‑123, [source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L104-L123))
- **setup** — Configuration shortcuts: monitors, keybindings, network (lines 126‑132, [source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L126-L132))
- **install**, **remove**, **update** — Package management actions
- **about**, **system** — Project info and power controls (lines 36‑42 for system actions, [source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc#L36-L42))

---

## Conditional Visibility with `when` and `checked`

The Omarchy menu definition supports reactive UI elements that adapt to system state.

**`when` — Show items only when conditions are met:**

```json
"trigger.power.laptop-saver": {
  "icon": "⚡",
  "label": "Laptop Power Saver",
  "when": "omarchy-hw-laptop",
  "action": "omarchy-toggle-power-saver"
}

```

Here, `omarchy-hw-laptop` is a shell predicate. If it returns non‑zero, the entry is hidden entirely.

**`checked` — Display toggle state:**

```json
"style.bar.visible": {
  "icon": "󰕮",
  "label": "Show Bar",
  "checked": "omarchy-get bar.visible",
  "action": "omarchy-toggle bar.visible"
}

```

The `omarchy-get` query runs each time the menu renders, showing a checkmark when the bar is enabled.

---

## Dynamic Providers in the Omarchy Menu

Static entries blend with **provider‑driven sub‑menus**. When `provider` is specified, Omarchy calls an external script to generate child items at runtime.

**The Apps provider** (most common dynamic source):

```json
"apps": {
  "icon": "󰀻",
  "label": "Apps",
  "aliases": ["app", "applications"],
  "provider": "apps"
}

```

The corresponding script at [`default/omarchy/providers/apps.sh`](https://github.com/omacom/omarchy/blob/main/default/omarchy/providers/apps.sh) scans `$PATH` and `$XDG_DATA_DIRS` for `.desktop` files, returning JSON that the shell converts to clickable entries. This keeps the installed application list always current without manual edits.

---

## Practical Examples for Customizing the Omarchy Menu

**Launch the menu from terminal:**

```bash
omarchy-menu

```

**Add a custom "Hello World" entry** — append to `omarchy-menu.jsonc`:

```json
"custom.hello": {
  "icon": "👋",
  "label": "Hello World",
  "action": "notify-send 'Hello from Omarchy!'"
}

```

After saving, run `omarchy-reload` to see the new entry under *Custom*.

**Create a conditional hardware entry:**

```json
"system.gpu.hybrid": {
  "icon": "󰢮",
  "label": "Hybrid GPU Mode",
  "when": "omarchy-hw-hybrid-gpu",
  "action": "omarchy-switch-gpu hybrid"
}

```

This appears only on machines where `omarchy-hw-hybrid-gpu` succeeds.

---

## Key Source Files for the Omarchy Menu System

| File | Role |
|------|------|
| `default/omarchy/omarchy-menu.jsonc` | Static menu definition ([source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc)) |
| [`default/omarchy/providers/apps.sh`](https://github.com/omacom/omarchy/blob/main/default/omarchy/providers/apps.sh) | Dynamic application list provider ([source](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/providers/apps.sh)) |
| `bin/omarchy-menu` | CLI launcher entry point ([source](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-menu)) |
| [`docs/menu.md`](https://github.com/omacom/omarchy/blob/main/docs/menu.md) | Schema documentation and validation rules ([source](https://github.com/omacom/omarchy/blob/quattro/docs/menu.md)) |

---

## Summary

- The Omarchy menu is **declared in JSON‑C** at `default/omarchy/omarchy-menu.jsonc`, parsed at shell startup
- Entries use **dot‑notation keys** for hierarchy and support seven standard properties including conditional `when` and toggle `checked`
- **Top‑level groups** (apps, learn, trigger, style, setup, system) organize functionality into logical sections
- **Dynamic providers** such as `apps` generate live submenu content from system state
- Changes require **no rebuild** — edit, save, and run `omarchy-reload` to apply

---

## Frequently Asked Questions

### What file format does the Omarchy menu use?

Omarchy uses **JSON‑C** (JSON with JavaScript‑style comments) for its menu definition. This allows inline documentation while maintaining parseability. The parser strips comments before processing, so standard JSON tools can also read the file if needed.

### How do I add a submenu in the Omarchy menu?

Use **dot notation in the key name**. For example, `"learn.keybindings"` creates a *Keybindings* entry inside the *Learn* group. Multiple dots create deeper nesting: `"trigger.capture.screenshot"` produces *Trigger → Capture → Screenshot*.

### Can the Omarchy menu show different items based on hardware?

Yes. The **`when`** property accepts any Bash expression. If it exits non‑zero, the entry is hidden. Common predicates include `omarchy-hw-laptop`, `omarchy-hw-hybrid-gpu`, and custom checks like `[ -f ~/.config/omarchy/experimental ]`.

### How does the Apps menu stay updated without editing the JSON file?

The **Apps menu uses a provider**. Instead of static entries, the `"provider": "apps"` declaration tells Omarchy to execute [`default/omarchy/providers/apps.sh`](https://github.com/omacom/omarchy/blob/main/default/omarchy/providers/apps.sh). This script queries the system for `.desktop` files and returns fresh JSON on every menu open, ensuring newly installed applications appear immediately.