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

> Learn how to configure the bar layout in Omarchy. This guide details using the shell.json file to customize left, center, and right widget sections with plugin descriptors.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Omarchy configures its top-bar layout through a single JSON file at [`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json). The `bar` object contains settings for position and appearance, plus a `layout` object with three keys: `left`, `center`, and `right`.

```json
{
  "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`](https://github.com/basecamp/omarchy/blob/main/shell/README.md), the loading process follows four stages:

1. **JSON parsing** – The shell reads [`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

# 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`:

```bash

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

```js
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`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json) | Primary user configuration for bar position, transparency, and widget layout |
| [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) | Developer documentation on bar configuration schema and runtime behavior |
| [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file—such as **[`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/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.