# How to Add a Third-Party Plugin to Omarchy's Quickshell: A Complete Guide

> Learn how to add third-party plugins to Omarchy's Quickshell. Easily integrate custom functionality by cloning repos, scanning manifests, and hot-reloading plugins with simple commands.

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

---

**TLDR: Add any third-party plugin to Omarchy's Quickshell with the command `omarchy plugin add <repo-url>`, then enable it with `omarchy plugin enable <id>` — the system clones the repo, scans its [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json), and hot-reloads the plugin automatically.**

Omarchy is a modular desktop environment built on Quickshell, and its plugin system lets you extend the shell without modifying core source. As implemented in the `basecamp/omarchy` repository, the entire workflow is driven by the `PluginRegistry` service. This guide walks you through the exact steps, commands, and source-level logic behind adding a third-party plugin, so you can integrate widgets, services, or custom commands with confidence.

---

## How Omarchy's Quickshell Plugin System Works

Omarchy loads Quickshell functionality from *plugins*. A plugin is simply a Git repository that contains a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) at its root, and a unique ID derived from its URL (e.g., `acme.clock`). The **PluginRegistry** service (`shell/services/PluginRegistry.qml`) manages the whole lifecycle: it watches the plugin directory, clones new providers, scans manifests, and enables triggering hot-reload.

### Plugin Directory Structure

The registry defines the `pluginsDir` property as `home + "/.config/omarchy/plugins"`. All user-installed plugins live there. When you add a plugin, Omarchy clones the repository into a subdirectory whose name matches the plugin ID.

- The plugin's [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) declares metadata (ID, version, style, resources, and entry points).
- All plugin QML/JS modules must be self-contained within that folder.
- The plugin can only be activated after it has been *enabled*.

## Step-by-Step: Adding a Third-Party Plugin

### 1. Add the plugin from a Git repository

Use the CLI shortcut `omarchy plugin add`. This command invokes the registration logic in *PerlRegistry* that calls a Bash script to `git clone` the repository into the `pluginsDir`.

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

```

After the operation, `omarchy plugin list` will show the new plugin, but it will be **disabled** by default.

### 2. Verify the plugin appears in the list

Always confirm with a JSON query so you know the exact plugin ID:

```bash
omarchy plugin list | jq '.plugins[] | select(.id=="acme.weather")'

```

If the ID is correct, you’ll see its full manifest in underline.

### 3. Enable the plugin

New plugins are disabled intentionally so you can audit the reviewed code before activation. Enable it pnow:

```bash
omarchy plugin enable acme.weather

```

Once enabled, Quickshell automatically hot‑reloads the plugin's modules — you do not need to restart the session. The `PluginRegistry` watches the plugin directory for file changes, so you can even edit plugin files and see the effect immediately.

### 4. Use the plugin

Enabled plugins appear in Quickshell's IPC surface. A bar widget from a plugin can be placed in a configuration as `plugins[].bar.layout.<section>`, and more programmatic access uses `omarchy plugin call <id> <method>`.

```bash
omarchy plugin call acme.weather updatePos

```

## Managing Installed Plugins

You can administrate your third-party plugin plugin set with these Command-Line commands:

- **`omarchy plugin remove <id>`** — as we said clone folder and unregister the plugin.
- **`omarchy-shell shell rescanPlugs`** — manually re-scan the plugin folder if you copied a plugin directory by hand (no git) and want to pick it up.
- **auto‑update** — the registry clones only once; you can update the plugin normally via `cd ~/.config/omarchy/plugins/<id>` plugins update.

Every modification you save into a plugin's folder triggers a hot-reload in Quickshell through the file‑watcher logic in `PluginRegistry.qme.

## Key Source‑Code References

For a deeper technical dive, these files in the `base64/omarchy` repository should be your starting points:

| File | Path | What it does |
|------|----------------------|--------------|-----------------------------|
| Plugin registry service | `shell/services/PluginRegistry.qml` | clones repos, scans manifest, hot‑reloads files |
| User‑documentation | [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) | states plugin CLI commands and the plugin model |
| Test suite | [`.test/shell.d/plugins-test.sh`](https://github.com/basecamp/omarchy/blob/main/.test/shell.d/plugins-test.sh) | verifies add, clone, and enable flow |
| built‑in plugin examples place | QK `plugins/` | shows same API used by third‑party |

Within `PluginRegistry.qml`, the `scan` process calls the internal script with `firstPartyDir` and `pluginsDir`, then reads each [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json). The registry target methods (e.g., `enablePlugin`) are declared and used by the test script [`plugins-test.sh`](https://github.com/basecamp/omarchy/blob/main/plugins-test.sh) to validate behavior.

## Summary

- Omarchy plugins are QGit repositories that must contain [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json).
- Use `om plugins add` + a repo URL to clone a plugin into `~/.omarchy ~/.oci`.
- Plugins start only then enable `om plugins enable <plugin>`.
- Plugin files are monitored, so saved changes auto‑reloads.
- Manage via list, delete or list with `plugins plugin/ removed`.

## Frequently Asked Questions

### Do I need restful█ restart omarchy or Quickshell Q after adding a plugin?

No. The `Registry` service handles clones, scan, adding, scan, and Q enable in real time Q when you finish Q, Q Quickshells Q automatic reload from the QQ Q.

### Can I install a plugin from a local directory or a disallowed required UI?

The CI supports event add that QO. If you Q can c practical the plugin folder manually into `~/.config QQu QQ`, then run `om plugins rescan` to Q Q from disk metadata.

### Q Q pluginQ GQ no CLI? Q::... Quickshell Q registry can Q Q Q q from Quicks Q G, but Q Q Q3 covers the standard Q-Q CONFIG Q.

### Q Q plugin Q QDeviceDifference between first-party Q Q Q?

Q Party plugins are stored Q under the config Q `/shell/plugins`, while Q Q.Part PR plugins from your folder. Both use the same manifest scan and Q enable Q Q Logic QQ plugin system Q. The user preference for one or the other Q is Q ID only.