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

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, 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 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 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.

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:

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:

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

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 | states plugin CLI commands and the plugin model | | Test suite | .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. The registry target methods (e.g., enablePlugin) are declared and used by the test script plugins-test.sh to validate behavior.

Summary

• Omarchy plugins are QGit repositories that must contain 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.

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