Where Are Third-Party Quickshell Plugins Cloned in Omarchy?

Third-party Quickshell plugins are cloned into ~/.config/omarchy/plugins/<plugin-id>/, while built-in first-party plugins reside in $OMARCHY_PATH/shell/plugins/.

The Omarchy desktop environment uses a strict two-tier plugin system that separates vendor-shipped functionality from user extensions. When working with third-party Quickshell plugins in the basecamp/omarchy repository, knowing the exact storage location is critical for installation, development, and debugging. This guide breaks down the directory architecture, cloning workflow, and runtime discovery mechanisms based on the official source code.

First-Party vs. Third-Party Plugin Locations

Omarchy’s plugin system distinguishes between two categories by their filesystem location.

First-party plugins live in the system directory at $OMARCHY_PATH/shell/plugins/. These ship with Omarchy and load automatically at startup without user intervention.

Third-party plugins reside in the user’s personal XDG configuration directory. According to comments in shell/services/PluginRegistry.qml at line 671, "Third-party plugins stay at the top level of ~/.config/omarchy/plugins." This separation allows users to install community extensions without modifying system files.

The Third-Party Quickshell Plugins Directory

Default Installation Path

When you execute the omarchy-plugin-clone command, the repository copies directly into a subdirectory of your configuration folder:

~/.config/omarchy/plugins/<plugin-id>/

This behavior is explicitly documented in shell/README.md at line 97, which states the command "clones it straight into ~/.config/omarchy/plugins/<id>/". The user-facing documentation in docs/omarchy-shell.md at line 54 reiterates this path as the canonical installation location.

Required Structure and Manifest

Every valid third-party plugin must contain a manifest.json file at its root. The PluginRegistry service scans for this file during initialization; directories without a manifest are ignored during the discovery phase.

How to Clone and Enable Third-Party Plugins

The repository provides a dedicated CLI helper at bin/omarchy-plugin-clone that automates git operations and directory placement.

# Clone a third-party plugin from any git repository

omarchy-plugin-clone https://github.com/user/example-plugin

# The command creates ~/.config/omarchy/plugins/example-plugin/

# Enable the plugin in your running session:

omarchy-shell plugin enable example-plugin

You can audit your current installation using bin/omarchy-plugin-list, which enumerates all plugins and indicates whether each is first-party or third-party.

Runtime Discovery and Hot-Reloading

The PluginRegistry.qml service implements a dual-path scanning mechanism. It resolves the user directory using Qt.resolvedUrl("file://" + Qt.applicationDirPath + "/../.config/omarchy/plugins") alongside the system path.

This architecture enables hot-reloading for development workflows. When you modify any file within the third-party plugin directory, Quickshell detects the filesystem change and updates the running UI instantly without requiring a restart.

# Edit a plugin configuration or source file

vim ~/.config/omarchy/plugins/example-plugin/manifest.json

# Save the file — changes appear immediately in the Quickshell interface

Summary

• Third-party Quickshell plugins install to ~/.config/omarchy/plugins/<plugin-id>/ as documented in shell/README.md and docs/omarchy-shell.md
• First-party plugins remain in the system path at $OMARCHY_PATH/shell/plugins/
• Each plugin requires a manifest.json at its root for the PluginRegistry to recognize it
• The bin/omarchy-plugin-clone command handles git cloning and directory placement automatically
• Modifications to files in the user directory trigger hot-reloading via the runtime registry scanner

Frequently Asked Questions

How do I know if a plugin is first-party or third-party?

Run the omarchy-plugin-list command. This utility (located at bin/omarchy-plugin-list) inspects the installation path of each plugin and labels it accordingly. Plugins in ~/.config/omarchy/plugins/ are marked as third-party, while those in $OMARCHY_PATH/shell/plugins/ are first-party.

Can I override a built-in first-party plugin with a third-party version?

Yes. The PluginRegistry service resolves plugin IDs from the user directory before checking the system directory. If you install a third-party plugin with the same ID as a built-in component, your version takes precedence, allowing you to customize or extend default functionality.

Do I need to restart Omarchy after cloning a new plugin?

No. The PluginRegistry continuously monitors ~/.config/omarchy/plugins/ for new directories and changes. After running omarchy-plugin-clone, the plugin appears in the available list immediately. You only need to run omarchy-shell plugin enable <id> to activate it in the current session.

What happens if I delete a plugin directory while Omarchy is running?

The registry detects the filesystem change and unloads the plugin components automatically. However, dependent configurations may throw errors until you update your shell configuration to remove references to the deleted plugin.

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