# How to Create and Install a Third-Party Plugin for Omarchy: A Complete Guide

> Learn to create and install a third-party plugin for Omarchy. Follow this guide to initialize a Git repository, add a manifest file, and install your plugin with the CLI.

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

---

**To create a third-party Omarchy plugin, initialize a Git repository with a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file that declares the plugin's `id`, `kinds`, and `entryPoints`, then install it via the CLI using `omarchy plugin add <git-url>`.**

The Omarchy desktop environment from `basecamp/omarchy` runs as a single long-running **Quickshell process** (`omarchy-shell`). All UI elements—including the bar, panels, overlays, and services—are implemented as **plugins** discovered at startup. Third-party plugins are standard Git repositories that extend this architecture without modifying core system files.

## Understanding the Plugin Architecture

Omarchy’s plugin system relies on **manifest-driven discovery**. When `omarchy-shell` initializes, it scans for directories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file at the root. According to the implementation in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) (lines 48-70), this manifest must declare the plugin's schema version, unique identifier, supported kinds, and entry points for each UI component.

Plugins are categorized by **kinds** such as `bar-widget`, `panel`, `overlay`, or `service`. Each kind determines how Omarchy integrates the plugin into the desktop environment. The shell loads these dynamically from `~/.config/omarchy/plugins/<manifest-id>/`, allowing users to add, remove, or update functionality without touching the core Omarchy installation.

## Creating a Third-Party Plugin

### Structuring the Repository

Create a new Git repository and add a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) at the root directory. This file serves as the contract between your code and the Omarchy shell. For a bar widget, you must also define a `barWidget` object that specifies the default section, display name, and configuration schema.

The minimal structure requires:

- [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) - Plugin metadata and entry points
- QML/JS files referenced in `entryPoints` (e.g., `Widget.qml` for bar widgets)

### Writing the manifest.json

The manifest must follow Omarchy’s schema as documented in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) (lines 48-70). Here is a complete example for a bar widget:

```json
{
  "schemaVersion": 1,
  "id": "my.org.cool-clock",
  "name": "Cool Clock",
  "version": "1.0.0",
  "author": "You",
  "description": "A clock widget with a custom format",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "Widget.qml" },
  "barWidget": {
    "displayName": "Cool Clock",
    "category": "Time",
    "allowMultiple": false,
    "defaultSection": "left",
    "defaults": { "format": "HH:mm" },
    "schema": [{ "key": "format", "type": "string", "label": "Format" }]
  }
}

```

Key fields include:
- **`id`**: A unique reverse-domain identifier for the plugin
- **`kinds`**: An array declaring what types of UI elements the plugin provides
- **`entryPoints`**: A map connecting each kind to its implementation file
- **`barWidget`**: Configuration specific to bar widgets, including `defaultSection` and `schema`

### Implementing Entry Points

The files referenced in `entryPoints` must be valid QML or JavaScript modules compatible with Quickshell. For bar widgets, the entry point typically exports a QML component that renders the widget UI. Ensure your implementation handles the configuration properties defined in the manifest's `schema` array.

## Installing and Managing Plugins

### Adding Plugins from Remote Repositories

Publish your repository to a Git host (e.g., GitHub), then install it using the Omarchy CLI. As documented in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) (lines 94-99), the command clones the repository into `~/.config/omarchy/plugins/<manifest-id>/`:

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

```

By default, plugins are added in a **disabled** state, allowing you to review the code before activation. To install and enable in one step:

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable --yes

```

### Enabling and Activating Plugins

Activation depends on the plugin kind:

- **Bar widgets**: After enabling the plugin, add its `id` to your bar layout using:
  ```bash
  omarchy bar move my.org.cool-clock --section right
  ```

  This updates `~/.config/omarchy/shell.json` under `bar.layout.<section>`.

- **Other kinds** (panels, overlays, services): Run `omarchy plugin enable <id>` to add the plugin to the `plugins[]` array in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json). These plugins activate immediately once enabled.

### Hot-Reload and Development Workflow

Omarchy supports **hot-reload** for rapid development. Any file saved under `~/.config/omarchy/plugins/` triggers an automatic reload of the affected plugin code. If changes are not picked up automatically, force a rescan using the IPC command:

```bash
omarchy-shell shell rescanPlugins

```

This functionality is detailed in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) (lines 44-46) and allows iterative development without restarting the desktop session.

### Updating and Removing Plugins

Update a specific plugin to the latest commit:

```bash
omarchy plugin update my.org.cool-clock

```

The CLI shows a diff before fast-forwarding. To update all Git-managed plugins:

```bash
omarchy plugin update --yes

```

Remove a plugin completely:

```bash
omarchy plugin remove my.org.cool-clock

```

## Safely Modifying Built-in Plugins

Instead of editing first-party plugins directly (which risks losing changes on update), **clone** them into your user configuration:

```bash
omarchy plugin clone omarchy.clock

```

This command copies the built-in plugin to your user directory with a **user-namespaced id** (e.g., `dhh.clock`) and preserves your layout and settings state, as noted in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) (lines 43-48). You can then modify the cloned version safely while maintaining the original as a fallback.

## Summary

- **Omarchy plugins** are Git repositories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) that declares `id`, `kinds`, and `entryPoints` to the Quickshell runtime.
- **Installation** uses `omarchy plugin add <git-url>`, cloning to `~/.config/omarchy/plugins/<manifest-id>/` with an optional `--enable` flag.
- **Bar widgets** require placement via `omarchy bar move <id> --section <left|center|right>` to appear in the shell layout.
- **Hot-reload** automatically detects file changes; use `omarchy-shell shell rescanPlugins` to force a manual refresh.
- **Built-in plugins** should be cloned via `omarchy plugin clone <id>` before modification to preserve changes across system updates.

## Frequently Asked Questions

### What is the minimum required structure for an Omarchy plugin?

A valid Omarchy plugin requires a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) at the repository root containing at minimum: `schemaVersion`, a unique `id`, `name`, `kinds` array, and `entryPoints` object mapping kinds to implementation files. For bar widgets, you must also include a `barWidget` configuration object defining the `defaultSection` and UI schema.

### How do I enable a plugin after installation?

Run `omarchy plugin enable <id>` to add the plugin to the `plugins[]` array in `~/.config/omarchy/shell.json`. For bar widgets, you must additionally position the widget using `omarchy bar move <id> --section <left|center|right>` to make it visible in the bar layout.

### Can I modify built-in Omarchy plugins safely?

Yes. Instead of editing files in the system directory, use `omarchy plugin clone <id>` to create a user-scoped copy with a namespaced identifier (e.g., `dhh.clock`). This preserves your modifications across system updates while keeping the original plugin intact.

### How does hot-reload work for plugin development?

Omarchy automatically reloads plugins when you save files under `~/.config/omarchy/plugins/`. If the shell does not detect changes, send `omarchy-shell shell rescanPlugins` to force a plugin rescan and reload without restarting your desktop session.