# What Is the Omarchy Shell? Architecture, Configuration, and Plugin System

> Discover the Omarchy Shell, a unified Quickshell process for the Omarchy desktop. Learn its architecture, central JSON configuration, and dynamic plugin system.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-05

---

**The Omarchy Shell is a single, persistent Quickshell process that hosts every visual and background component of the Omarchy desktop environment through a dynamic plugin system configured via one centralized JSON file.**

The Omarchy Shell serves as the core runtime for the Omarchy desktop environment, maintained in the `omacom/omarchy` repository. Unlike traditional desktop shells that spawn separate processes for each UI element, this architecture runs as one long-running Quickshell instance that dynamically loads plugins for the top bar, menus, panels, overlays, and background services. All user customization lives in a single configuration file, making the Omarchy Shell both resource-efficient and straightforward to modify.

## Architecture and Process Model

At its foundation, the Omarchy Shell operates as a single Quickshell process named `omarchy-shell`. When Hyprland initializes a graphical session, it launches the shell via `quickshell -p $OMARCHY_PATH/shell`, which loads `shell/shell.qml` as the entry point. This monolithic-but-modular design eliminates per-plugin process overhead by hosting every component—bar widgets, panels, lock screens, and headless services—inside one persistent process.

The `ShellRoot` component defined in `shell/shell.qml` initializes the system and wires the **PluginRegistry**. Rather than spawning separate binaries for each UI element, plugins are loaded dynamically into this single process space, significantly reducing memory usage and inter-process communication latency.

## Configuration via shell.json

All customizable state for the Omarchy Shell resides in `~/.config/omarchy/shell.json`. If this file is absent, the system falls back to defaults shipped at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json). The configuration system performs a **complete override** rather than merging; creating a user configuration replaces all defaults entirely.

The JSON structure defines idle timers, bar placement, transparency settings, and widget arrangements:

```json
{
  "version": 1,
  "idle": { "screensaver": 150, "lock": 300 },
  "bar": {
    "position": "top",
    "transparent": false,
    "centerAnchor": "omarchy.clock",
    "layout": {
      "left":   [{ "id": "omarchy.menu" }, { "id": "omarchy.workspaces" }],
      "center": [{ "id": "omarchy.clock", "format": "HH:mm" }],
      "right":  [{ "id": "omarchy.tray" }]
    }
  },
  "plugins": [],
  "disabledPlugins": []
}

```

Key configuration fields control:
- **idle**: Screensaver activation and screen lock timeouts in seconds
- **bar.position**: Vertical placement (`"top"` or `"bottom"`)
- **bar.layout**: Three sections (`left`, `center`, `right`) containing widget arrays
- **plugins**: Array of enabled non-bar plugins (panels, overlays, menus)
- **disabledPlugins**: Array of explicitly disabled built-in service IDs

## Plugin System and Types

Plugins extend the Omarchy Shell without requiring process restarts. First-party plugins reside in `shell/plugins/` while third-party plugins live in `~/.config/omarchy/plugins/`. Each plugin directory contains a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) describing its type and entry points.

Supported plugin kinds include:
- **bar-widget**: Interactive elements embedded within bar sections
- **panel**: Full-screen or floating information panels
- **overlay**: Transient visual overlays and notifications
- **menu**: Contextual and application menus
- **service**: Headless background processes (e.g., battery monitoring)
- **bar**: Complete bar replacements

The `shell/services/PluginRegistry.qml` component handles manifest validation, dependency resolution, and dynamic loading. A plugin is considered **enabled** when its ID appears in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json)—either within a bar layout section, the `plugins` array, or implicitly for first-party services unless listed in `disabledPlugins`.

## IPC Commands and Runtime Control

The Omarchy Shell exposes an IPC target named `shell` (supplemented by plugin-specific targets) for runtime manipulation. The `bin/omarchy-shell` wrapper binary forwards CLI commands to the running process via `quickshell ipc`.

Core IPC commands include:
- **ping**: Verify shell responsiveness
- **summon/hide/toggle**: Control visibility of toggleable UI elements
- **call**: Execute plugin-specific methods with arguments
- **rescanPlugins**: Force discovery and validation of new plugins
- **reloadConfig**: Apply configuration changes without restart
- **setPluginEnabled**: Programmatically enable or disable plugins
- **listPlugins**: Display loaded plugin metadata and status

These commands enable scriptable control over the desktop environment without editing configuration files directly.

## Practical Configuration Examples

### Reorganizing the Bar Layout

To move the clock widget from the center to the left section programmatically:

```bash
omarchy bar move omarchy.clock --section left --index 0

```

This invokes `PluginRegistry.moveBarWidget()` in the running shell, updates `~/.config/omarchy/shell.json` atomically, and refreshes the bar layout without restarting the session.

### Enabling Third-Party Plugins

Assuming a weather plugin with ID `acme.weather` exists in `~/.config/omarchy/plugins/acme.weather/`:

```bash
omarchy plugin enable acme.weather

```

Alternatively, manual configuration achieves the same result by appending `{ "id": "acme.weather" }` to the `plugins` array in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json).

### Disabling Built-in Services

To prevent the battery monitoring service from loading:

```bash
omarchy plugin disable omarchy.battery

```

This appends `omarchy.battery` to the `disabledPlugins` array, preventing the service from initializing while preserving the plugin files.

### Reloading Configuration

After manual edits to `~/.config/omarchy/shell.json`, apply changes immediately:

```bash
omarchy-shell shell reloadConfig

```

### Rescanning for New Plugins

When installing plugins via git checkout or manual extraction, force a discovery scan:

```bash
omarchy-shell shell rescanPlugins

```

The shell also watches `~/.config/omarchy/plugins/` for changes and reloads automatically when files are added or modified.

## Summary

- The Omarchy Shell runs as a single Quickshell process (`omarchy-shell`) that dynamically loads all UI components and services as plugins, eliminating multi-process overhead.
- Configuration is centralized in `~/.config/omarchy/shell.json`, which completely overrides system defaults without merging behavior.
- Plugins are categorized as `bar-widget`, `panel`, `overlay`, `menu`, `service`, or `bar`, residing in `shell/plugins/` (first-party) or `~/.config/omarchy/plugins/` (third-party).
- Runtime control is achieved through IPC commands exposed via the `shell` target, accessible through the `omarchy-shell` helper binary.
- The PluginRegistry in `shell/services/PluginRegistry.qml` manages enablement states, bar layout manipulation, and automatic rescanning of plugin directories.

## Frequently Asked Questions

### What process runs the Omarchy Shell?

The Omarchy Shell executes as a single, persistent Quickshell process named `omarchy-shell`, launched by Hyprland through `quickshell -p $OMARCHY_PATH/shell`. This process defined in `shell/shell.qml` hosts every visual element and background service internally, avoiding the memory overhead of spawning separate processes for each widget or panel.

### Where is the Omarchy Shell configuration stored?

User-specific configuration resides at `~/.config/omarchy/shell.json`. If this file does not exist, the shell loads defaults from [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) within the Omarchy installation directory. When a user configuration exists, it replaces all defaults entirely; the system does not perform deep merging between user and default settings.

### How do I add a new plugin to the Omarchy Shell?

Install the plugin by placing its directory in `~/.config/omarchy/plugins/` with a valid [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) file, then enable it via `omarchy plugin enable <plugin-id>` or by manually adding the ID to the `plugins` array in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json). If the shell does not detect the plugin automatically, execute `omarchy-shell shell rescanPlugins` to force a filesystem scan.

### Can I disable built-in services that start automatically?

Yes. First-party services are enabled by default but can be disabled by running `omarchy plugin disable <service-id>` or adding the ID to the `disabledPlugins` array in `~/.config/omarchy/shell.json`. This prevents the service from loading during shell initialization without requiring deletion of the plugin files from `shell/plugins/`.