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

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 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)

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

• apps — Application launcher with dynamic provider
• learn — Documentation and keybinding helpers (lines 45‑53, source)
• trigger — Quick utilities: emoji picker, screenshots, hardware toggles (lines 56‑73, source)
• style — Theme, background, and bar customization (lines 104‑123, source)
• setup — Configuration shortcuts: monitors, keybindings, network (lines 126‑132, source)
• install, remove, update — Package management actions
• about, system — Project info and power controls (lines 36‑42 for system actions, source)

---

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:

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

"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):

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

The corresponding script at 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:

omarchy-menu

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

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

"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)
default/omarchy/providers/apps.sh	Dynamic application list provider (source)
bin/omarchy-menu	CLI launcher entry point (source)
docs/menu.md	Schema documentation and validation rules (source)

---

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. This script queries the system for .desktop files and returns fresh JSON on every menu open, ensuring newly installed applications appear immediately.

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