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

To create a third-party Omarchy plugin, initialize a Git repository with a 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 file at the root. According to the implementation in 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 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 - 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 (lines 48-70). Here is a complete example for a bar widget:

{
  "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 (lines 94-99), the command clones the repository into ~/.config/omarchy/plugins/<manifest-id>/:

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:

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:

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

omarchy-shell shell rescanPlugins

This functionality is detailed in 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:

omarchy plugin update my.org.cool-clock

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

omarchy plugin update --yes

Remove a plugin completely:

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:

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

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