How to Develop and Install Third-Party Plugins for Omarchy Shell

Omarchy Shell loads third-party plugins from ~/.config/omarchy/plugins/<plugin-id>/ directories containing a manifest.json file and QML assets, automatically hot-reloading changes when you develop locally.

Omarchy Shell, the extensible desktop environment from the basecamp/omarchy repository, supports third-party plugins written in QML and JavaScript. These plugins extend the shell's functionality through a well-defined manifest contract and a set of CLI tools for validation, installation, and management.

Understanding the Plugin Architecture

Omarchy Shell discovers plugins through a registry system that scans both built-in and user directories. The architecture relies on a strict manifest contract defined in shell/plugins/README.md and enforced by validation scripts.

The Manifest Contract

Every plugin must include a manifest.json at its root directory. This file declares the plugin's identity, version, kind (such as bar-widget, panel, or service), and entry points. The schema requires valid JSON, which you can verify using jq -e . before installation.

Plugin Registry and Discovery

The shell uses bin/omarchy-plugin-catalog to scan $OMARCHY_PATH/shell/plugins (built-in) and $HOME/.config/omarchy/plugins (user-installed), emitting a JSON list of all available plugins. Before any plugin loads, bin/omarchy-plugin-validate checks the manifest against the schema to prevent runtime errors.

Developing a Third-Party Plugin

Creating a plugin involves setting up a directory structure, authoring the manifest, and implementing QML components. The shell watches for file changes and hot-reloads the plugin automatically during development.

Step 1: Create the Plugin Directory

Create a new directory for your plugin, either as a local folder or a Git repository. The directory name should match your plugin ID for clarity, though the actual identifier comes from the id field in manifest.json.

Step 2: Define the manifest.json

Create a manifest.json file at the root. The manifest must specify schemaVersion, id, name, version, kinds, and entryPoints.

{
  "schemaVersion": 1,
  "id": "acme.weather",
  "name": "Weather Panel",
  "version": "0.1.0",
  "kinds": ["bar-widget"],
  "entryPoints": {
    "barWidget": "BarWidget.qml"
  },
  "omarchy": {
    "defaultSection": "center"
  }
}

Step 3: Implement QML Assets

Place the QML files referenced in entryPoints adjacent to the manifest or in subdirectories. For a bar-widget kind, you must provide the QML file specified in the barWidget entry point.

import QtQuick 2.15
import QtQuick.Controls 2.15

Item {
    width: 120; height: 24
    Text {
        anchors.centerIn: parent
        text: "Hello, Omarchy!"
        color: Theme.foreground
    }
}

Step 4: Validate Locally

Before installation, run omarchy-plugin-validate against your plugin directory. This executes the same checks the shell performs before loading.

omarchy-plugin-validate /path/to/your/plugin

Installing and Enabling Plugins

Once developed, install your plugin into the shell's user configuration directory and activate it using the provided CLI tools.

Local Installation

Use bin/omarchy-plugin-add to copy your plugin directory into ~/.config/omarchy/plugins/<id>/ and automatically run validation.

omarchy-plugin-add /path/to/your/plugin --yes

Remote Installation

For plugins hosted on GitHub or other Git remotes, use bin/omarchy-plugin-clone. This clones the repository, preserves dependencies, and enables the plugin automatically.

omarchy-plugin-clone https://github.com/acme/weather-plugin.git

Enabling and Placement

Activate your plugin using bin/omarchy-plugin-enable. For bar widgets, specify the placement section using the --section flag.

# Default placement

omarchy-plugin-enable acme.weather

# Specific section placement

omarchy-plugin-enable acme.weather --section bottom

To deactivate a plugin, use bin/omarchy-plugin-disable.

Hot-Reload and Iteration

Omarchy Shell monitors ~/.config/omarchy/plugins/**/manifest.json and referenced QML files for changes. When you edit your plugin's code, the shell reloads it automatically without requiring a session restart, as verified in test/shell.d/runtime-smoke-test.sh.

Verify loaded plugins through the shell's IPC:

shell_ipc shell listPlugins | jq .

Summary

• Third-party plugins require a manifest.json at the root and QML assets in the same directory or subfolders
• Install plugins locally using omarchy-plugin-add or remotely via omarchy-plugin-clone
• Validate manifests with omarchy-plugin-validate before installation to catch schema errors
• Enable and configure placement using omarchy-plugin-enable and omarchy-plugin-disable
• The shell hot-reloads plugins automatically when files change in ~/.config/omarchy/plugins/

Frequently Asked Questions

What file structure is required for an Omarchy Shell plugin?

A plugin must be a directory containing a manifest.json file at the root and any QML or JavaScript files referenced in the manifest's entryPoints. After installation, the directory resides under ~/.config/omarchy/plugins/<plugin-id>/ where the shell continuously monitors it for changes.

How do I validate my plugin before installing it?

Run omarchy-plugin-validate /path/to/your/plugin to check the manifest against the schema. This script performs the same validation the shell runs before loading a plugin, ensuring your manifest.json is valid JSON and contains all required fields such as schemaVersion, id, and kinds.

Can I develop plugins without restarting the shell?

Yes. Omarchy Shell watches the ~/.config/omarchy/plugins/ directory and hot-reloads plugins automatically when you modify the manifest.json or referenced QML files. This behavior is tested in test/shell.d/runtime-smoke-test.sh, allowing you to iterate on your code without session interruption.

How do I distribute my plugin to other users?

Package your plugin as a Git repository containing the manifest.json and QML assets. Users can install it using omarchy-plugin-clone <repository-url>, which clones the repo into ~/.config/omarchy/plugins/, validates the manifest, and enables the plugin automatically.

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