# How to Install and Enable Plugins in Omarchy: A Complete Guide > Learn how to install and enable Omarchy plugins easily. Follow our guide to clone repositories and activate plugins within the Omarchy shell UI for enhanced functionality. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **To install and enable plugins in Omarchy, run `omarchy plugin add ` to clone the repository into `~/.config/omarchy/plugins/`, then run `omarchy plugin enable ` 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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//`. 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`](https://github.com/omacom/omarchy/blob/main/manifest.json) structure. Run the following command: ```bash omarchy plugin add https://github.com//.git ``` The `bin/omarchy-plugin-add` script handles the cloning operation, placing the files into `~/.config/omarchy/plugins//` as documented in [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/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: ```bash ls ~/.config/omarchy/plugins// cat ~/.config/omarchy/plugins//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: ```bash omarchy plugin enable ``` 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`](https://github.com/omacom/omarchy/blob/main/manifest.json) and registers the defined kinds without requiring a full restart. As confirmed by [`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/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: ```bash 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: ```bash omarchy plugin remove ``` 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/manifest.json) describing its functionality - **Installation uses `omarchy plugin add`**: Clones to `~/.config/omarchy/plugins//` 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`](https://github.com/omacom/omarchy/blob/main/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//` before executing it. You must explicitly run `omarchy plugin enable ` 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`](https://github.com/omacom/omarchy/blob/main/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//`. Each plugin occupies its own subdirectory containing the cloned Git repository files, including the mandatory [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json). This location keeps user extensions separate from the core shell code installed in `shell/plugins/`.