# How to Configure Omarchy Shell with shell.json for Bar, Idle Timeout, and Plugins

> Learn to configure Omarchy shell.json for bar auto-hide, idle timeouts, and plugins. Customize your Quickshell desktop environment efficiently.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-11

---

**You configure Omarchy's Quickshell-based desktop environment by editing [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) to set bar auto-hide timeouts via the `idle` object and load optional plugins through the root `plugins` array.**

The Omarchy window manager uses a QML-powered compositor that reads JSON configuration from the `omacom/omarchy` repository. Modifying [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) allows you to control how long the panel remains visible after inactivity and which background services or bar widgets are active.

## Locating the Main Configuration File

The primary configuration file lives at [[`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json)](https://github.com/omacom/omarchy/blob/quattro/config/omarchy/shell.json) in the repository root. This file is parsed by Quickshell on startup and determines the behavior of the top bar, idle detection services, and visual transitions. According to the [Omarchy shell documentation](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md), all user-facing customizations for the panel and its extensions route through this single JSON entry point.

## Adjusting Bar Idle Timeout Settings

The bar's auto-hide behavior is governed by a top-level `idle` configuration object. This section defines how many seconds the panel waits before fading out and which plugins support the idle detection logic.

### Understanding the idle object structure

The `idle` object accepts three key properties:

- **`timeout`** – Integer value in seconds defining the period of inactivity before the bar hides
- **`fadeDuration`** – Float value controlling the animation speed of the hide/show transition
- **`plugins`** – Array listing service plugins required for idle functionality (typically including `omarchy.idle`)

In [[`shell/plugins/services/idle/manifest.json`](https://github.com/omacom/omarchy/blob/main/shell/plugins/services/idle/manifest.json)](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/services/idle/manifest.json), the idle service exposes the detection mechanisms that [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) references.

### Example timeout configuration

To keep the bar visible for 15 seconds after the last input before fading over 0.3 seconds, modify the `idle` block as follows:

```json
{
  "idle": {
    "timeout": 15,
    "fadeDuration": 0.3,
    "plugins": ["omarchy.idle"]
  }
}

```

Setting `timeout` to `0` typically disables auto-hide behavior, while values between `5` and `30` suit most productivity workflows.

## Enabling and Loading Plugins

Plugins extend Omarchy with background services and bar widgets. You activate them by adding their manifest identifiers to the root-level `plugins` array in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json).

### Core services vs bar widgets

The registry distinguishes between two plugin types:

- **Service plugins** – Background agents like idle detection, night-light control, and media monitoring that run without UI elements
- **Bar widgets** – Visual components such as workspace switches, system trays, and window titles that render in the panel

Service manifests reside under `shell/plugins/services/`, while bar widget manifests live in `shell/plugins/bar/widgets/`.

### Adding nightlight and media controls

To enable the night-light service and media controls alongside the default bar and idle plugins, populate the `plugins` array as shown:

```json
{
  "plugins": [
    "omarchy.bar",
    "omarchy.idle",
    "omarchy.nightlight",
    "omarchy.media"
  ]
}

```

Each identifier corresponds to an `id` field within its respective manifest. For example, `omarchy.nightlight` maps to [[`shell/plugins/services/nightlight/manifest.json`](https://github.com/omacom/omarchy/blob/main/shell/plugins/services/nightlight/manifest.json)](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/services/nightlight/manifest.json), and `omarchy.media` maps to [[`shell/plugins/services/media/manifest.json`](https://github.com/omacom/omarchy/blob/main/shell/plugins/services/media/manifest.json)](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/services/media/manifest.json).

### Including bar widgets

Individual bar widgets follow the same registration pattern but use longer identifiers reflecting their path. To add the Workspaces switcher and System Update indicator:

```json
{
  "plugins": [
    "omarchy.bar",
    "omarchy.idle",
    "omarchy.bar.widgets.Workspaces",
    "omarchy.bar.widgets.SystemUpdate"
  ]
}

```

These entries reference manifests like [[`shell/plugins/bar/widgets/Workspaces.manifest.json`](https://github.com/omacom/omarchy/blob/main/shell/plugins/bar/widgets/Workspaces.manifest.json)](https://github.com/omacom/omarchy/blob/quattro/shell/plugins/bar/widgets/Workspaces.manifest.json).

## Applying Changes

After editing [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json), propagate the configuration using the Omarchy refresh helper:

```bash
omarchy-refresh-config omarchy/shell.json

```

This command reloads the JSON without requiring a full system restart. The Quickshell compositor picks up new timeout values and plugin registrations on the next rendering cycle.

## Summary

- **Primary config location**: [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) controls all shell behavior in the `omacom/omarchy` repository
- **Idle timeout**: Set via the `idle.timeout` property (seconds) and `idle.fadeDuration` (seconds as float) within the `idle` object
- **Plugin activation**: Add manifest identifiers to the root `plugins` array; services live under `shell/plugins/services/` and widgets under `shell/plugins/bar/widgets/`
- **Required idle plugin**: Always include `omarchy.idle` in the `idle.plugins` array when configuring auto-hide behavior
- **Refresh command**: Run `omarchy-refresh-config omarchy/shell.json` to apply edits without rebooting

## Frequently Asked Questions

### Where is the shell.json file located in the Omarchy repository?

The file is located at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) in the repository root. This path is relative to the `omacom/omarchy` clone directory and is referenced by the Quickshell compositor during initialization.

### What unit of measurement does the idle timeout use?

The `timeout` value inside the `idle` object uses **seconds** expressed as integers. The `fadeDuration` property uses seconds expressed as floating-point numbers (e.g., `0.25` for a quarter-second animation).

### How do I add a custom bar widget to the configuration?

Identify the widget's manifest file under `shell/plugins/bar/widgets/` (such as [`Workspaces.manifest.json`](https://github.com/omacom/omarchy/blob/main/Workspaces.manifest.json)), note its `id` field (typically formatted as `omarchy.bar.widgets.WidgetName`), and append that string to the root `plugins` array in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json).

### Do I need to restart my session after editing shell.json?

No. Execute `omarchy-refresh-config omarchy/shell.json` from a terminal to reload the configuration. The Quickshell compositor processes the updated JSON immediately, applying new idle timeouts and loading newly specified plugins without requiring a logout or reboot.