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

> Learn how to develop and install third-party plugins for Omarchy Shell. Discover automatic hot-reloading and QML asset integration for seamless plugin development.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Omarchy Shell loads third-party plugins from `~/.config/omarchy/plugins/<plugin-id>/` directories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md) and enforced by validation scripts.

### The Manifest Contract

Every plugin must include a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/manifest.json).

### Step 2: Define the manifest.json

Create a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file at the root. The manifest must specify `schemaVersion`, `id`, `name`, `version`, `kinds`, and `entryPoints`.

```json
{
  "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.

```qml
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.

```bash
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.

```bash
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.

```bash
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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh).

Verify loaded plugins through the shell's IPC:

```bash
shell_ipc shell listPlugins | jq .

```

## Summary

- Third-party plugins require a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/manifest.json) or referenced QML files. This behavior is tested in [`test/shell.d/runtime-smoke-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.