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

You configure Omarchy's Quickshell-based desktop environment by editing 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 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/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, 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/quattro/shell/plugins/services/idle/manifest.json), the idle service exposes the detection mechanisms that 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:

{
  "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.

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:

{
  "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/quattro/shell/plugins/services/nightlight/manifest.json), and omarchy.media maps to [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:

{
  "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/quattro/shell/plugins/bar/widgets/Workspaces.manifest.json).

Applying Changes

After editing shell.json, propagate the configuration using the Omarchy refresh helper:

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 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 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), note its id field (typically formatted as omarchy.bar.widgets.WidgetName), and append that string to the root plugins array in 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.

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