Core Components of Omarchy: The Modular Desktop Environment Explained

Omarchy is built around nine core architectural components—omarchy-shell (the Quickshell runtime), a CLI command suite, a bar and widget framework, a manifest-based plugin system, an agent/skill framework, a declarative theming system, a notification service, a user configuration layout, and update helpers—that work together to provide a script-driven, extensible desktop environment.

Omarchy is a highly configurable desktop environment developed by Basecamp that leverages a lightweight Quickshell host to drive its user interface and inter-process communication. Unlike monolithic desktop environments, Omarchy separates its core runtime from extensible plugins, AI-assisted agents, and declarative theming systems, allowing deep customization without recompiling source code. Understanding these core components reveals how the system balances simplicity with enterprise-grade flexibility.

The Runtime Core: omarchy-shell

At the heart of Omarchy lies omarchy-shell, a long-running Quickshell host process that serves as the central nervous system of the desktop environment. According to the [shell/README.md](https://github.com/basecamp/omarchy/blob/quattro/shell/README.md), this component drives the UI, manages IPC (Inter-Process Communication), and orchestrates the plugin system.

The shell exposes an IPC channel that other components use to communicate, ensuring that the core runtime remains lightweight while external scripts handle specific functionality. This design allows omarchy-shell to load bars, overlays, and services on demand without restarting the entire session.

Command and Control Interface

CLI Command Suite (omarchy-*)

Omarchy provides user interaction through a collection of thin Bash wrappers located in the bin/ directory. These commands, prefixed with omarchy-, communicate with the running shell via the IPC channel rather than implementing logic directly.

For example, bin/omarchy-toggle demonstrates how CLI tools send commands to the shell to toggle UI states or trigger actions. This architecture keeps the command line interface decoupled from the core runtime, allowing users to create automation hooks and shortcuts that interact with the live desktop environment.

Bar and Widget Framework

The visual interface is constructed from first-party plugins that render the top bar, system tray, and quick-access widgets. These plugins—including omarchy.bar, omarchy.clock, omarchy.media, omarchy.network, and omarchy.power—are documented in [shell/plugins/README.md](https://github.com/basecamp/omarchy/blob/quattro/shell/plugins/README.md).

Widget behavior and bar layout are configurable through ~/.config/omarchy/shell.json, which the shell reads at startup to determine which plugins to load and how to arrange them. Each widget runs as a discrete component that registers with the shell through the plugin system.

Extensibility Architecture

Plugin System

Omarchy achieves modularity through a manifest-based plugin system where each plugin resides under shell/plugins/<id>/ and declares its capabilities via a manifest.json file. As shown in [shell/plugins/bar/manifest.json](https://github.com/basecamp/omarchy/blob/quattro/shell/plugins/bar/manifest.json), plugins specify their kind—whether bar-widget, overlay, or service—and their entry QML file.

This structure allows both first-party and third-party extensions to integrate seamlessly without modifying core source code. The shell loads these plugins on demand based on user configuration, keeping the base installation lightweight while supporting complex customizations.

Agent and Skill Framework

For AI-assisted functionality, Omarchy implements an agent framework composed of Bash scripts located under default/agents/skills/. Each skill is a standalone script that the shell can invoke to perform tasks such as crash diagnosis or code generation.

The file [default/agents/skills/omarchy/capture.md](https://github.com/basecamp/omarchy/blob/quattro/default/agents/skills/omarchy/capture.md) illustrates how these skills are structured and documented. Users can invoke agents directly from the shell or through CLI commands, enabling extensible automation that operates independently of the core binary.

Configuration and Theming

Declarative Theming System

Appearance customization in Omarchy is fully declarative, driven by color tables stored in themes/*/colors.toml, template files under default/themed/*.tpl, and helper commands like omarchy-theme-*. The default color definitions in [themes/default/colors.toml](https://github.com/basecamp/omarchy/blob/quattro/themes/default/colors.toml) provide the base palette used by the bar, notifications, and overlays.

Users can switch themes or create custom variants by modifying these TOML files and template assets, with changes applying system-wide without touching compiled code.

Configuration Layout

Default configuration files live under config/omarchy/ and are copied to ~/.config/omarchy/ on first run, as documented in [docs/file-layout.md](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md). This layout includes shell.json for plugin management, theme configurations, and agent settings.

The omarchy-refresh-config command ensures users can reset or update their local configuration to match current defaults without manual file operations.

System Services and Maintenance

Notification Service

Desktop alerts, crash-capture notices, and AI-agent prompts are handled by a dedicated notification service implemented in QML. The file shell/plugins/notifications/Service.qml provides a centralized service for transient UI messages, ensuring consistent styling and behavior across all system notifications.

Update and Package Management

Omarchy maintains its own package repository and AUR integration through commands like bin/omarchy-update. These helpers synchronize Omarchy-specific packages with Arch Linux's core/extra/multilib repositories while managing dependencies specific to the desktop environment.

Practical Usage Examples

The modular architecture enables granular control over the desktop environment through simple commands:

# Display the current bar layout from ~/.config/omarchy/shell.json

omarchy bar list

# Enable the clock widget via the plugin system

omarchy plugin enable omarchy.clock

# Switch to the dark theme variant

omarchy theme-set dark

# Run AI-assisted crash diagnosis on process ID 1234

omarchy agent crash 1234

# Refresh default configuration files for Hyprland integration

omarchy-refresh-config hypr/hyprland.lua

Summary

• omarchy-shell serves as the lightweight Quickshell runtime that drives UI, IPC, and plugin loading.
• CLI commands (omarchy-*) act as thin wrappers that communicate with the shell via IPC channels.
• Plugins use manifest files (manifest.json) to register bar-widgets, overlays, and services without core modifications.
• Agents and skills provide AI-assisted functionality through standalone Bash scripts under default/agents/skills/.
• Theming relies on declarative TOML color tables and templates, allowing appearance changes without code edits.
• Configuration follows a predictable layout under ~/.config/omarchy/ with defaults stored in config/omarchy/.
• Notification services and update helpers complete the architecture by handling system alerts and package management.

Frequently Asked Questions

What is omarchy-shell and how does it work?

omarchy-shell is the core Quickshell host process that runs continuously as the desktop environment's runtime engine. It manages the UI, handles inter-process communication through an IPC channel, and loads plugins on demand based on user configuration, ensuring the system remains lightweight while supporting complex extensions.

How do Omarchy plugins handle registration and loading?

Plugins reside in shell/plugins/<id>/ directories and declare their type (bar-widget, overlay, or service) through a manifest.json file. The shell reads these manifests at startup to determine which QML files to load and how to integrate them into the active interface, allowing third-party extensions to function alongside first-party components.

Can I customize Omarchy's appearance without modifying source code?

Yes, the theming system is fully declarative and user-editable. Colors are defined in TOML files under themes/, templates live in default/themed/, and the omarchy theme-set command applies changes instantly. This separation allows users to swap color schemes and modify widget styling without touching the underlying QML or compiled binaries.

How does Omarchy handle system updates and package management?

Omarchy includes dedicated update helpers such as omarchy-update that synchronize the system's own package repository with Arch Linux's standard repositories. These tools manage AUR integration and ensure that Omarchy-specific components stay current while respecting the host system's package management conventions.

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