Omarchy Shell Bar Layout Configuration: JSON Schema, Loading Logic, and Runtime Updates

The Omarchy shell bar layout is defined in ~/.config/omarchy/shell.json using a JSON object with left, center, and right arrays that specify widget IDs and optional size parameters, which the shell validates and hot-reloads without requiring a restart.

The Omarchy desktop environment uses a declarative configuration system to render its top-level status bar. Understanding the Omarchy shell bar layout configuration file format and loading behavior enables precise control over widget placement, spacing, and runtime customization.

Configuration File Location and Schema

The primary configuration resides at ~/.config/omarchy/shell.json, falling back to the repository default at $OMARCHY_PATH/config/omarchy/shell.json when the user file is absent or malformed. The JSON schema requires a top-level version field set to 1 and a bar object containing a layout dictionary with three mandatory arrays: left, center, and right.

{
  "version": 1,
  "bar": {
    "layout": {
      "left":   [{ "id": "omarchy.workspaces", "size": 2 }],
      "center": [{ "id": "omarchy.clock" }],
      "right":  [{ "id": "omarchy.tray" }]
    }
  },
  "plugins": []
}

Each entry requires an id property matching a registered plugin identifier (e.g., omarchy.clock). The optional size numeric hint controls relative spacing allocation. Widget entries may also be plain strings; the shell normalizes these to object form during initialization, as verified by the plugin registry test that checks "clone restoration normalizes string entries" at line 346 in test/shell.d/fixtures/plugin-registry/shell.qml.

Loading Mechanism and Validation

In shell/shell.qml, the loading logic prioritizes the user configuration file, defaulting to the system path when unavailable. The implementation at lines 30-34 handles this fallback chain. The shell enforces schema compliance through the test suite in test/shell.d/config-test.sh at line 16, which validates the presence of the version: 1 field and the three layout arrays. Upon successful validation, the Bar component receives the resolved configuration via the barConfig property, injected by shell.qml during initialization.

Runtime Modifications and Hot-Reloading

Changes to the layout propagate immediately through a hot-reload mechanism that replaces the entire bar subtree rather than performing deep merges. This behavior is documented in shell/plugins/bar/README.md at lines 12-18. Because the file is the single source of truth, any change is picked up by the running shell through its hot-reload mechanism—no deep-merge is performed; the whole bar subtree is replaced with the new JSON content.

The omarchy bar CLI provides imperative manipulation commands. For example, adding a widget to the right section:

omarchy bar add omarchy.battery --section right

This command updates the shell.json file directly, inserting the widget ID into the specified array. The running shell detects the file change and reconstructs the bar layout accordingly.

Default Layout and Widget Settings

The repository ships with a default configuration placing workspaces on the left, a clock in the center, and a system tray on the right. This default is asserted in test/shell.d/clock-test.sh at line 264, which verifies the center section contains the clock widget.

Individual widget instances receive their configuration through shell/Ui/BarWidget.qml, which parses the settings property from each layout entry at line 9. This allows per-widget customization such as custom formats or display modes within the declarative JSON structure.

Practical Configuration Examples

Adding Multiple Widgets to the Center Section

{
  "version": 1,
  "bar": {
    "layout": {
      "left":   [{ "id": "omarchy.workspaces" }],
      "center": [
        { "id": "omarchy.clock" },
        { "id": "omarchy.weather" }
      ],
      "right":  [{ "id": "omarchy.tray" }]
    }
  }
}

Save this to ~/.config/omarchy/shell.json to display both clock and weather widgets centered in the bar.

Programmatic Widget Removal

Within QML scripts or plugins, interact with the registry to remove widgets dynamically:

// Remove battery widget from layout
registry.putBarWidget("omarchy.battery", { remove: true });

The registry updates the underlying JSON array, triggering the bar's reactive reconstruction.

Summary

• Omarchy shell bar layout configuration resides in ~/.config/omarchy/shell.json with a fallback to $OMARCHY_PATH/config/omarchy/shell.json.
• The JSON schema requires version: 1 and three arrays (left, center, right) containing widget objects with id and optional size properties.
• shell/shell.qml (lines 30-34) implements the loading priority and validation logic confirmed by test/shell.d/config-test.sh (line 16).
• Runtime changes trigger hot-reload of the entire bar subtree without deep merging, as documented in shell/plugins/bar/README.md (lines 12-18).
• The CLI command omarchy bar add [widget-id] --section [left|center|right] manipulates the configuration file directly.
• shell/Ui/BarWidget.qml (line 9) handles per-widget settings parsing from the layout entries.

Frequently Asked Questions

Where is the Omarchy bar layout configuration file stored?

The primary user configuration is located at ~/.config/omarchy/shell.json. If this file is missing or contains invalid JSON, the shell falls back to the default configuration at $OMARCHY_PATH/config/omarchy/shell.json, as implemented in shell/shell.qml at lines 30-34.

What properties are required for each widget entry in the layout arrays?

Each entry must include an id property containing the plugin identifier (e.g., omarchy.clock). An optional size integer controls spatial allocation. Entries may be specified as plain strings or objects; the shell normalizes strings to object form during initialization according to the test logic at line 346 of test/shell.d/fixtures/plugin-registry/shell.qml.

How does the Omarchy shell handle configuration changes while running?

The shell implements a hot-reload mechanism that monitors the configuration file for changes. When detected, it replaces the entire bar subtree with the new configuration rather than merging changes selectively. This behavior ensures the file remains the single source of truth and is documented in shell/plugins/bar/README.md at lines 12-18.

Can I rearrange widgets without manually editing the JSON file?

Yes. The omarchy bar CLI provides sub-commands to manipulate the layout programmatically. For example, omarchy bar add omarchy.battery --section right appends the battery widget to the right section, automatically updating shell.json and triggering the hot-reload mechanism.

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