# How Omarchy Installs and Manages Third-Party Plugins: The Complete Guide

> Learn how Omarchy installs and manages third-party plugins using Git repositories and CLI commands. This complete guide details the process for the omacom/omarchy project.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-08

---

**Omarchy treats every third-party plugin as a Git repository containing a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) file, installing them into `~/.config/omarchy/plugins/` and managing their lifecycle through CLI commands that update the [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) configuration.**

Omarchy is a Qt-based desktop shell that supports deep customization through third-party plugins distributed as Git repositories. Understanding how the shell discovers, validates, and isolates these extensions is essential for both users installing community enhancements and developers building new UI components.

## The Git-Based Plugin Architecture

Omarchy's plugin system is built entirely on Git. Each third-party plugin is a standalone repository that the shell clones directly into the user's configuration directory. According to the Omarchy source code, the shell maintains plugins at `~/.config/omarchy/plugins/<id>/`, where `<id>` corresponds to the plugin's unique identifier defined in its manifest.

The core discovery mechanism lives in `shell/services/PluginRegistry.qml`. At startup and whenever `rescanPlugins` is invoked, this registry walks the plugins directory, loads each [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json), and builds **capability-scoped facades** that restrict what third-party code can access. This architecture prevents untrusted plugins from reaching privileged services while still allowing full UI integration for legitimate components.

## Installing Third-Party Plugins

### The Installation Process

When you run `omarchy plugin add <git-url>`, the system executes `bin/omarchy-plugin-add`, which performs three critical operations:

1. **Clones** the remote repository into `~/.config/omarchy/plugins/<id>/`
2. **Validates** the [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) structure against the schema defined in `shell/services/PluginRegistry.qml`
3. **Disables** the plugin by default so you can inspect the code before activation

```bash

# Install a third-party weather widget

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

# The plugin remains disabled until you explicitly enable it

omarchy plugin enable community.weather-extra

```

### Manual Installation Method

You can also install plugins manually without using the CLI:

```bash

# Create the plugin directory

mkdir -p ~/.config/omarchy/plugins/acme.clock

# Copy your plugin files

cp -r /path/to/local/clock/* ~/.config/omarchy/plugins/acme.clock/

# Rescan and enable

omarchy-shell shell rescanPlugins
omarchy plugin enable acme.clock

```

## The Plugin Manifest Format

Every third-party plugin must contain a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) at its root. The `shell/services/PluginRegistry.qml` validates this schema strictly. Here is the required structure:

```json
{
  "schemaVersion": 1,
  "id": "my.org.cool-clock",
  "name": "Cool clock",
  "version": "1.0.0",
  "author": "You",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "Widget.qml" }
}

```

**Key fields:**
- **`kinds`**: Declares which UI surfaces the plugin targets (e.g., `bar`, `panel`, `bar-widget`)
- **`entryPoints`**: Maps each kind to a specific QML file that the shell instantiates
- **`id`**: The unique reverse-domain identifier used for the directory name and [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) entries

## Enabling and Disabling Plugins

Security-conscious by design, Omarchy keeps newly installed plugins disabled by default. The `bin/omarchy-plugin-enable` command activates a plugin by appending its ID to the `plugins[]` array in [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json):

```json
{
  "plugins": [
    { "id": "community.weather-extra" },
    { "id": "acme.system-monitor" }
  ]
}

```

To disable a plugin without removing it, use `bin/omarchy-plugin-disable`, which removes the entry from [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) while optionally keeping service instances alive:

```bash

# Disable but keep running (for smooth transitions)

omarchy plugin disable community.weather-extra

```

## Managing Plugin Lifecycle

### Updating Plugins

The `bin/omarchy-plugin-update` command pulls fast-forward changes from the remote repository, runs validation against `shell/services/PluginRegistry.qml`, and triggers a rescan. The system shows a diff before applying changes and re-validates the [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) schema:

```bash

# Update a specific plugin

omarchy plugin update community.weather-extra

# Update all installed third-party plugins

omarchy plugin update

```

### Removing Plugins

To completely remove a third-party plugin, `bin/omarchy-plugin-remove` deletes the plugin directory at `~/.config/omarchy/plugins/<id>/` and purges its entry from [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json):

```bash

# Remove the weather widget completely

omarchy plugin remove community.weather-extra

```

### Cloning Built-in Plugins

For customization, `bin/omarchy-plugin-clone` creates a local copy of built-in plugins so you can modify them:

```bash

# Clone the default bar for editing

omarchy plugin clone default-bar

```

## Security and Isolation via PluginRegistry

The `shell/services/PluginRegistry.qml` implements a sophisticated security model. When it scans `~/.config/omarchy/plugins/*`, it constructs different **facades** based on the `kinds` declared in the manifest:

- A `bar-widget` receives a lightweight UI facade with limited API surface
- A full `bar` plugin receives a comprehensive service facade
- Privileged system services remain inaccessible to all third-party code

Additionally, the shell supports **hot-reloading**: whenever any file under the plugin's directory changes, the shell reloads the QML code instantly without requiring a desktop restart, enabling rapid development cycles while maintaining security boundaries.

## Summary

- **Git-based distribution**: Third-party plugins install as Git repos into `~/.config/omarchy/plugins/<id>/` via `omarchy plugin add <git-url>`
- **Manifest-driven**: Every plugin requires a root [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) declaring `id`, `kinds`, and `entryPoints` validated by `shell/services/PluginRegistry.qml`
- **Secure by default**: New plugins install disabled; activation requires `omarchy plugin enable <id>` which updates [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json)
- **Capability isolation**: The PluginRegistry builds scoped facades preventing third-party code from accessing privileged services
- **Full lifecycle support**: Update with `omarchy plugin update`, remove with `omarchy plugin remove`, and clone built-ins with `omarchy plugin clone`

## Frequently Asked Questions

### What is the required format for the plugin manifest.json?

The manifest must include `schemaVersion`, `id`, `name`, `version`, `author`, `kinds`, and `entryPoints`. The `kinds` field declares which UI components the plugin implements (such as `bar-widget` or `panel`), while `entryPoints` maps each kind to a specific QML file path. The `shell/services/PluginRegistry.qml` validates this schema strictly when scanning `~/.config/omarchy/plugins/`.

### How does Omarchy prevent third-party plugins from accessing system functions?

Omarchy's `PluginRegistry` creates capability-scoped facades that expose only the APIs appropriate for the declared `kinds`. For example, a plugin declaring `bar-widget` receives a restricted UI facade, while the shell prevents direct access to privileged services regardless of the plugin's declared capabilities.

### Can I install plugins without using the `omarchy plugin add` command?

Yes. You can manually copy plugin files to `~/.config/omarchy/plugins/<id>/` and then run `omarchy-shell shell rescanPlugins` followed by `omarchy plugin enable <id>`. This method bypasses the automatic Git cloning but still requires a valid [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) for the PluginRegistry to recognize the plugin.

### Does Omarchy support hot-reloading for plugin development?

Yes. The shell monitors file changes within each plugin's directory under `~/.config/omarchy/plugins/` and hot-reloads the QML code instantly without requiring a desktop restart. This feature allows developers to see changes immediately while working on `entryPoints` files like `Widget.qml`.