# Omarchy Shell Configuration (shell.json) Reference: A Complete Guide

> Explore the Omarchy shell.json configuration reference. Master your Quickshell environment by customizing the status bar layout, plugins, and idle behavior with instant hot-reloading.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: api-reference
- Published: 2026-09-10

---

**The [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) file in `~/.config/omarchy/` is the central configuration that controls the Omarchy Quickshell environment, including the status bar layout, plugins, and idle behavior, with hot-reloading support that applies changes instantly without restarting.**

The Omarchy shell configuration drives every aspect of the Quickshell desktop environment, from widget placement to screen locking behavior. This JSON-based configuration file defines how the status bar renders, which plugins are active, and when the screensaver activates. Understanding its structure is essential for customizing the Omarchy experience according to the `omacom/omarchy` source code.

## Configuration File Location and Loading Behavior

The shell loads configuration from two possible locations, prioritizing user customizations over system defaults shipped in the repository.

### Default vs. User Configuration

When no personal configuration exists, the shell loads defaults from [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) within the Omarchy repository. This file ships with the application and provides the baseline settings for the status bar, plugins, and idle timers. However, once you create or modify `~/.config/omarchy/shell.json`, the shell switches to user-mode operation exclusively.

### Canonical Mode and Hot-Reloading

After you edit `~/.config/omarchy/shell.json`, the file becomes **canonical**—the shell stops merging default values and uses your file verbatim. This means new default widgets added in future Omarchy releases will not appear automatically; you must add them manually to your configuration if desired. The shell hot-reloads this file on every save, so no restart is required to see changes.

## Key Configuration Sections

The [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) structure consists of several top-level blocks that control specific shell behaviors, documented in [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md).

### Bar Settings (`bar` block)

The **`bar`** object holds all status-bar-related settings, including position and layout. This block controls where the bar appears on screen and how widgets are arranged within it. You can modify bar position using the CLI helper:

```bash
omarchy bar set position top

```

This command updates the `bar.position` field in your user configuration file and triggers an immediate reload.

### Plugin Management (`plugins` and `disabledPlugins`)

The **`plugins[]`** array lists third-party plugins that should be enabled, while **`disabledPlugins[]`** contains first-party plugins that have been turned off. As documented in [`manual/32-shell-plugins.md`](https://github.com/omacom/omarchy/blob/main/manual/32-shell-plugins.md), Omarchy distinguishes between built-in plugins (which you disable) and external plugins (which you explicitly enable).

To enable a third-party plugin, add its ID to the plugins array:

```bash
jq '.plugins += ["myWidget"]' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

```

To disable a built-in plugin like "network":

```bash
jq '.disabledPlugins += ["network"]' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

```

The plugin remains present in the codebase but will not be loaded by the shell.

### Idle and Screensaver Settings (`idle` block)

The **`idle`** block controls screensaver and lock timers. For example, setting `idle.lock` to `600` locks the screen after ten minutes of inactivity, as explained in [`manual/13-toggles-idle-screensaver.md`](https://github.com/omacom/omarchy/blob/main/manual/13-toggles-idle-screensaver.md). This section manages power management and security behaviors.

To set the idle lock timeout:

```bash
jq '.idle.lock = 600' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

```

## Inspecting and Managing Configuration

Omarchy provides CLI helpers to interact with [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) without manual JSON editing, documented in [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md).

### Viewing Effective Configuration

To see the complete configuration currently in use—including merged defaults when no user file exists—run:

```bash
omarchy listShellConfig

```

This outputs the full JSON view that the shell is actively using, helpful for debugging configuration issues and verifying your changes.

### CLI Configuration Helpers

Instead of editing JSON directly, you can use commands like `omarchy bar set` and `omarchy bar defaults` to manipulate specific values. These helpers validate input and ensure proper JSON structure while safely updating `~/.config/omarchy/shell.json`.

## Summary

- **[`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json)** is the single source of truth for Omarchy Quickshell configuration, stored in `~/.config/omarchy/shell.json`.
- The file becomes **canonical** once edited, meaning new default widgets from updates won't appear unless manually added to your configuration.
- Configuration changes **hot-reload instantly** without requiring a shell restart.
- Key sections include **`bar`** (layout), **`plugins[]`** (third-party), **`disabledPlugins[]`** (built-in), and **`idle`** (screensaver/lock).
- Use **`omarchy listShellConfig`** to view the effective configuration and **`omarchy bar set`** for simple modifications.

## Frequently Asked Questions

### Where is the Omarchy shell configuration file located?

The user-specific configuration file is located at `~/.config/omarchy/shell.json`. If this file does not exist, the shell falls back to the default configuration shipped with the application at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) in the Omarchy repository at `omacom/omarchy`.

### How do I view the current effective configuration?

Run `omarchy listShellConfig` in your terminal. This command prints the complete JSON configuration that the shell is currently using, showing either the merged defaults or your canonical user configuration depending on whether you have customized the file.

### Why aren't new default widgets appearing after an Omarchy update?

Once you edit `~/.config/omarchy/shell.json`, it becomes a canonical configuration file. The shell stops merging new default widgets from updates into your setup. To add new default features introduced in updates, you must manually edit your configuration file to include them.

### How do I disable a built-in plugin without deleting its files?

Add the plugin ID to the `disabledPlugins` array in your [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json). For example, to disable the network plugin, use `jq '.disabledPlugins += ["network"]' ~/.config/omarchy/shell.json`. The plugin files remain in the codebase at their original locations but will not be loaded by the shell.