How to Install and Enable Plugins in Omarchy: A Complete Guide

To install and enable plugins in Omarchy, run omarchy plugin add <git-url> to clone the repository into ~/.config/omarchy/plugins/, then run omarchy plugin enable <plugin-id> to activate it in the shell UI.

Omarchy, the extensible desktop shell from the omacom/omarchy repository, treats every extension as a Git-based plugin containing a manifest.json file. This architecture allows users to install third-party widgets and services while maintaining strict control over when code becomes active. Follow this guide to manage the complete lifecycle of plugins, from initial installation through enabling, updating, and removal.

What Is an Omarchy Plugin?

An Omarchy plugin is a small Git repository that contains a manifest.json describing its capabilities. According to the source code in omacom/omarchy, the shell clones these repositories into the user's plugin directory at ~/.config/omarchy/plugins/<id>/. Each plugin can register multiple kinds (such as bar, bar-widget, or service) that define how the extension integrates into the desktop shell.

By default, newly added plugins remain disabled so you can inspect the code before it becomes active. This security-focused design prevents automatic execution of untrusted code immediately after cloning.

Installing a Plugin

To install and enable plugins in Omarchy, you first add the plugin using the CLI. This clones the repository and validates the manifest.json structure.

Run the following command:

omarchy plugin add https://github.com/<user>/<plugin>.git

The bin/omarchy-plugin-add script handles the cloning operation, placing the files into ~/.config/omarchy/plugins/<id>/ as documented in docs/omarchy-shell.md. After installation, the plugin exists on disk but does not yet appear in the UI.

The Plugin Structure

Once cloned, every plugin directory contains:

• manifest.json: Defines the plugin ID, kinds, and entry points
• Source files: Implementation code loaded by the shell

You can inspect a plugin before enabling it:

ls ~/.config/omarchy/plugins/<plugin-id>/
cat ~/.config/omarchy/plugins/<plugin-id>/manifest.json

Enabling a Plugin

After reviewing the code, enable the plugin to insert it into the appropriate place in the shell UI (e.g., a bar widget or menu entry).

Execute:

omarchy plugin enable <plugin-id>

The bin/omarchy-plugin-enable wrapper marks the plugin as active in the registry. The shell's plugin registration logic in shell/plugins/* reads the manifest.json and registers the defined kinds without requiring a full restart. As confirmed by test/shell.d/runtime-smoke-test.sh, plugins support hot-reloading, meaning they become active immediately after enabling.

Managing Installed Plugins

Beyond the initial install and enable workflow, Omarchy provides commands to maintain your plugin ecosystem.

Updating Plugins

To fetch the latest changes for all installed plugins:

omarchy plugin update

This command, implemented in bin/omarchy-plugin-update, fetches remote changes, displays a diff for review, and fast-forwards the local repository. This ensures you can audit changes before they take effect.

Removing Plugins

To permanently delete a plugin from your system:

omarchy plugin remove <plugin-id>

The bin/omarchy-plugin-remove script deletes the directory from ~/.config/omarchy/plugins/ and unregisters the plugin from the shell.

How Plugin Registration Works

Under the hood, the plugin registry walks the ~/.config/omarchy/plugins/ directory and reads each manifest.json file. The registration logic in shell/plugins/* processes these manifests to determine which UI components to load. IPC commands such as listPlugins and rescanPlugins allow the shell to refresh its view of available extensions dynamically.

Summary

• Plugins are Git repositories: Each contains a manifest.json describing its functionality
• Installation uses omarchy plugin add: Clones to ~/.config/omarchy/plugins/<id>/ but leaves the plugin disabled by default
• Enable with omarchy plugin enable: Activates the plugin in the UI without requiring a shell restart
• Update safely: omarchy plugin update shows diffs before fast-forwarding
• Remove completely: omarchy plugin remove deletes the plugin directory and unregisters it

Frequently Asked Questions

What file format defines an Omarchy plugin?

Every plugin must include a manifest.json file at its root. This JSON file specifies the plugin ID, the kinds of components it provides (such as bar-widget or service), and the entry points for loading code. The shell's plugin registry in shell/plugins/* parses this file during the scanning process.

Why are plugins disabled by default after installation?

Omarchy disables plugins by default as a security measure. This design allows you to inspect the cloned source code in ~/.config/omarchy/plugins/<id>/ before executing it. You must explicitly run omarchy plugin enable <plugin-id> to activate the plugin, ensuring no untrusted code runs automatically.

Can I update plugins without restarting Omarchy?

Yes. The shell supports hot-reloading of plugins. According to test/shell.d/runtime-smoke-test.sh, you can add, enable, or update plugins while the shell is running, and the changes take effect immediately without requiring a full restart. Use omarchy plugin update to fetch changes and apply them dynamically.

Where are third-party plugins stored on disk?

Third-party plugins are stored in ~/.config/omarchy/plugins/<plugin-id>/. Each plugin occupies its own subdirectory containing the cloned Git repository files, including the mandatory manifest.json. This location keeps user extensions separate from the core shell code installed in shell/plugins/.

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