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

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

{
  "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 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—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:

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

omarchy plugin enable acme.weather

Alternatively, manual configuration achieves the same result by appending { "id": "acme.weather" } to the plugins array in shell.json.

Disabling Built-in Services

To prevent the battery monitoring service from loading:

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:

omarchy-shell shell reloadConfig

Rescanning for New Plugins

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

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 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 file, then enable it via omarchy plugin enable <plugin-id> or by manually adding the ID to the plugins array in 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/.

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