Understanding the omarchy-menu.jsonc Schema and Dynamic Menu Providers

The omarchy-menu.jsonc file is a JSON-C (JSON with comments) configuration that defines Omarchy's entire top-level menu hierarchy, while providers are QML-based components referenced via the "provider" field to dynamically generate submenu contents at runtime.

Omarchy is an open-source desktop environment developed by Basecamp. The omarchy-menu.jsonc schema serves as the central configuration file that structures the entire menu system, while providers inject dynamic functionality by generating entries on-the-fly based on system state.

What Is the omarchy-menu.jsonc Schema?

The omarchy-menu.jsonc file located at default/omarchy/omarchy-menu.jsonc uses JSON-C format—standard JSON with support for comments—to define the menu hierarchy. Each entry consists of a key-value pair where the key represents the menu-item ID (using dots to indicate nesting levels) and the value is a configuration object describing the item's appearance and behavior.

As documented in lines 4-9 of the source file, the schema supports extensive customization through specific fields that control visibility, interactivity, and dynamic content generation.

Core Schema Fields

The following fields define how each menu item behaves:

• icon: Unicode glyph displayed beside the label (e.g., "icon":"󰀻").
• label: Human-readable text shown in the menu (e.g., "label":"Apps").
• action: Shell command executed when selected; omitting this creates a submenu instead of an actionable item.
• provider: Special field referencing a QML provider that supplies dynamic submenu entries at runtime (e.g., "provider":"apps").
• aliases: Alternative searchable names for the omarchy menu summon <name> command.
• title: Header text displayed when the submenu opens (defaults to the label if omitted).
• when: Shell condition that determines visibility; the item hides if the condition fails.
• checked: Shell condition that appends a ✓ when evaluated successfully.
• disabled: Shell condition that dims the item and prevents selection while keeping it visible.
• iconFont: Custom font family for the icon when it differs from the menu's default font.

How Providers Work in Omarchy

Providers are built-in QML components that supply submenu contents dynamically. When a menu entry specifies "provider":"<name>", the system delegates content generation to the corresponding provider defined in shell/plugins/menu/Menu.qml.

Unlike static entries, provider-driven submenus do not list their contents in the JSONC file. Instead, the provider queries system state—such as installed applications or available fonts—and populates the list when the user opens the submenu.

Provider Implementation Details

Providers are declared within the providers map in shell/plugins/menu/Menu.qml. Because providers are implemented in QML, you cannot add new providers directly in the JSONC file; extending the menu with custom dynamic submenus requires modifying the QML source. The JSONC file merely references existing providers by name.

When a user selects a provider-backed item, the QML implementation invokes the provider's logic, which returns a dynamic list of entries based on current system configuration.

Built-in Provider Examples

The Omarchy source code includes several built-in providers:

• apps: Enumerates installed applications for the Apps submenu.
• fonts: Lists available system fonts for the Style → Font submenu.

For example, the Apps top-level entry uses the apps provider:

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

When selected, the apps provider generates a real-time list of launchable applications rather than reading from static configuration.

Practical Configuration Examples

These examples from the Omarchy source demonstrate common configuration patterns.

Static Toggle Without Provider

A simple toggle entry that executes a shell command:

"trigger.toggle.idle-lock": {
  "icon":"󰅶",
  "label":"Stay Awake",
  "action":"omarchy-toggle-idle"
}

Dynamic Submenu via Provider

The Style → Font submenu uses the fonts provider to list available fonts dynamically:

"style.font": {
  "icon":"",
  "label":"Font",
  "provider":"fonts"
}

Conditional Visibility

Show the Suspend option only when the user hasn't disabled the suspend-off toggle:

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

Checked State for Default Browser

Indicate the current default browser with a checkmark using the checked field:

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

Key Source Files

Understanding the menu system requires familiarity with three primary files:

• default/omarchy/omarchy-menu.jsonc: Contains the central menu definition and field documentation according to the Basecamp Omarchy repository.
• shell/plugins/menu/Menu.qml: Implements the QML providers map and handles rendering, searching, and invocation logic.
• docs/menu.md: Provides human-readable documentation of the format and provider architecture.

Summary

• The omarchy-menu.jsonc schema uses JSON-C format to define the entire Omarchy menu hierarchy through hierarchical key-value pairs.
• Menu items support conditional visibility (when), checked states (checked), and disabled states via shell command evaluation.
• Providers are QML components defined in shell/plugins/menu/Menu.qml that generate submenu contents dynamically at runtime.
• Built-in providers include apps for installed applications and fonts for system fonts.
• New providers cannot be added through JSONC configuration alone; they require QML implementation in the source code.

Frequently Asked Questions

What file format does omarchy-menu.jsonc use?

The file uses JSON-C (JSON with comments), which allows standard JSON syntax plus C-style comments for documentation. The actual file path is default/omarchy/omarchy-menu.jsonc in the Omarchy repository.

How do I add a new dynamic submenu to the Omarchy menu?

You cannot add new dynamic submenus through the JSONC file alone. According to the source code in shell/plugins/menu/Menu.qml, providers must be implemented in QML and registered in the providers map. Once implemented in QML, you can reference the provider name in the JSONC file using the "provider" field.

What is the difference between the action and provider fields?

The action field specifies a static shell command to execute when the user selects the item, creating a clickable menu entry. The provider field indicates that the item is a submenu whose contents are generated dynamically by a QML component; entries with providers do not use static action commands for navigation.

Can I use conditions to show or hide specific menu items?

Yes. The schema supports three conditional fields evaluated as shell commands: when controls visibility (hides the item if the condition fails), checked displays a checkmark when the condition succeeds, and disabled dims the item while preventing selection when the condition is true.

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