How to Configure the Bar Layout in Omarchy: A Complete Guide

Omarchy configures its top-bar layout through a single JSON file at config/omarchy/shell.json, where the bar object defines left, center, and right widget sections using ordered arrays of plugin descriptors.

The bar layout in Omarchy is entirely user-editable, making it straightforward to customize which widgets appear and where. This article walks through the configuration structure, how the shell interprets it, and practical ways to modify the bar at runtime.

Bar Configuration Structure

The primary configuration lives in config/omarchy/shell.json. The bar object contains settings for position and appearance, plus a layout object with three keys: left, center, and right.

{
  "bar": {
    "position": "top",
    "transparent": false,
    "centerAnchor": "omarchy.clock",
    "layout": {
      "left": [
        { "id": "omarchy.menu" },
        { "id": "omarchy.workspaces" }
      ],
      "center": [
        { "id": "omarchy.indicators" },
        { "id": "omarchy.clock", "format": "dddd HH:mm" },
        { "id": "omarchy.keyboard-layout" },
        { "id": "omarchy.weather" },
        { "id": "omarchy.system-update" }
      ],
      "right": [
        { "id": "omarchy.tray" },
        { "id": "omarchy.agents" },
        { "id": "omarchy.bluetooth" },
        { "id": "omarchy.network" },
        { "id": "omarchy.audio" },
        { "id": "omarchy.monitor" },
        { "id": "omarchy.power" }
      ]
    }
  }
}

Each widget descriptor requires at minimum an id field referencing a built-in or third-party plugin. Additional properties like format for the clock are passed through to the plugin's QML component.

How the Shell Loads the Bar Layout

According to the Omarchy source code in shell/README.md, the loading process follows four stages:

1. JSON parsing – The shell reads config/omarchy/shell.json and creates a runtime config.bar object.

2. Plugin resolution – shell/services/PluginRegistry.qml matches each widget id to a plugin manifest. Valid bar plugins must declare "kinds": ["bar"] in their shell/plugins/bar/manifest.json and provide a QML entry point.

3. Visual ordering – The shell iterates layout.left, layout.center, and layout.right arrays sequentially, loading each QML component into the corresponding bar section.

4. Dynamic updates – Runtime commands mutate the arrays and trigger configuration reloads without restarting the session.

Modifying the Bar Layout

Command-Line Widget Management

Use omarchy-bar put to add or reposition widgets dynamically. The command updates the JSON configuration and refreshes the bar UI.

# Insert "omarchy.bluetooth" after "omarchy.tray" on the right side

HOME="$HOME" OMARCHY_PATH="$PWD" "$PWD/bin/omarchy-bar" put omarchy.bluetooth --after omarchy.tray

Toggling Bar Visibility

Temporarily disable or re-enable the entire bar with omarchy-toggle-bar:

# Turn bar off for current session

HOME="$HOME" "$PWD/bin/omarchy-toggle-bar" off

# Re-enable (idempotent)

HOME="$HOME" "$PWD/bin/omarchy-toggle-bar" on

Programmatic Configuration Changes

For scripts running in the shell QML context, modify widget properties directly:

let cfg = Omarchy.config;  // loads config/omarchy/shell.json

// Update clock format
cfg.bar.layout.center
  .find(w => w.id === "omarchy.clock")
  .format = "HH:mm";

Omarchy.saveConfig(cfg);   // persists changes to disk

Key Files in the Bar Layout System

File	Purpose
config/omarchy/shell.json	Primary user configuration for bar position, transparency, and widget layout
docs/omarchy-shell.md	Developer documentation on bar configuration schema and runtime behavior
shell/plugins/bar/manifest.json	Declares bar plugin kind and QML entry point (Bar.qml)
shell/services/PluginRegistry.qml	Resolves widget IDs to QML components and validates plugin declarations
test/shell.d/runtime-smoke-test.sh	Verifies default layout and dynamic mutations via omarchy-bar and omarchy-toggle-bar

Summary

• Single file configuration – All bar layout settings live in config/omarchy/shell.json
• Three sections – left, center, and right arrays control widget placement
• Plugin-based widgets – Each id resolves to a QML component through PluginRegistry.qml
• Runtime editable – Changes via CLI tools or QML APIs apply without session restart

Frequently Asked Questions

What file controls the Omarchy bar layout?

The bar layout is defined entirely in config/omarchy/shell.json. This JSON file contains the bar object with position, transparent, and layout properties that determine how the top-bar appears and which widgets it contains.

Can I rearrange bar widgets without restarting Omarchy?

Yes. Use the omarchy-bar put command to insert, move, or reorder widgets at runtime. The shell detects configuration changes and updates the bar UI immediately. The test suite in test/shell.d/runtime-smoke-test.sh validates this behavior.

What properties are required for a bar widget descriptor?

Every widget descriptor must include an id field referencing a registered plugin. Additional properties depend on the specific widget—for example, the clock widget accepts a format string. The plugin registry in shell/services/PluginRegistry.qml validates that each id maps to a plugin declaring "kinds": ["bar"].

How do bar plugins declare themselves to Omarchy?

Bar plugins expose a manifest.json file—such as shell/plugins/bar/manifest.json—that specifies "kinds": ["bar"] and points to a QML entry point. The PluginRegistry.qml service discovers these manifests at startup and loads the corresponding components when referenced in the layout configuration.

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