# How to Add Third-Party Plugins to Omarchy: CLI and Manual Methods

> Easily add third-party plugins to Omarchy using CLI or manual methods. Learn how to install and manage plugins for enhanced functionality.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Third-party plugins in Omarchy are installed as isolated Git repositories under `~/.config/omarchy/plugins/` and managed through the `omarchy plugin` CLI commands, requiring explicit enablement after installation for security auditing.**

The `omacom/omarchy` repository implements a modular plugin architecture that treats every extension as an independent Git repository. When you add third-party plugins to Omarchy, the shell dynamically discovers them through a **plugin manifest** ([`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json)) and exposes their functionality via an IPC surface used by both the shell and command-line tools.

## Understanding the Omarchy Plugin Architecture

Omarchy stores all plugins—both built-in and third-party—in the user configuration directory at `~/.config/omarchy/plugins/`. Each plugin resides in its own subdirectory identified by the plugin's unique **id**.

At the root of every plugin repository, a **[`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json)** file declares the plugin's metadata, including its `id`, `kinds` (such as `bar`, `bar-widget`, or `panel`), and optional flags like `keepLoaded`. When the shell starts, it walks the `plugins` directory, reads every manifest, and constructs a runtime registry that maps plugin IDs to their entry-point QML/JS files.

This registry powers the IPC surface exposed to the system, supporting commands such as `listPlugins`, `summon`, `call`, and `rescanPlugins`. These interfaces allow the CLI tools and the graphical shell to interact with loaded extensions dynamically.

## Installing Third-Party Plugins Using the CLI

The `bin/omarchy-plugin-*` command suite provides a streamlined workflow for adding, enabling, updating, and removing plugins. According to [[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md), this process follows a strict audit-first paradigm where plugins are installed in a disabled state.

### Adding a Plugin Repository

Use the `omarchy plugin add` command to clone a third-party repository into the plugins directory. The CLI derives the target directory name from the plugin's manifest `id` field.

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git

```

This command invokes `bin/omarchy-plugin-add`, which performs a Git clone into `~/.config/omarchy/plugins/<id>/`. The plugin remains **disabled by default**, allowing you to review the source code before activation. As documented in [[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md#installing-a-third-party-plugin) (lines 49-56), this security measure prevents automatic execution of untrusted code.

### Enabling the Plugin

After auditing the plugin's code, activate it using the enable command:

```bash
omarchy plugin enable acme.weather

```

The `bin/omarchy-plugin-enable` wrapper appends the plugin ID to the `enabledPlugins[]` array in your user configuration and triggers a **hot-reload** of the plugin code. This makes the plugin's services immediately available to the shell without requiring a full restart (lines 83-84).

### Updating Installed Plugins

To fetch the latest changes from upstream, run the update command:

```bash
omarchy plugin update

```

This executes `bin/omarchy-plugin-update`, which performs a `git fetch`, displays a diff of incoming changes, and fast-forwards the local repository only upon your confirmation. The manifest is re-validated during the reload process to ensure compatibility (line 57).

### Removing Plugins

To completely uninstall a plugin and clean up its registry entries:

```bash
omarchy plugin remove acme.weather

```

The `bin/omarchy-plugin-remove` command safely deletes the plugin directory under `~/.config/omarchy/plugins/` and updates the runtime registry (line 58).

## Manual Installation for Offline and Custom Plugins

For scenarios where Git access is unavailable or you are developing plugins locally, Omarchy supports manual installation by directly copying plugin directories.

Copy your prepared plugin folder into the configuration directory:

```bash
cp -r /path/to/my-plugin ~/.config/omarchy/plugins/my-plugin

```

Then force the shell to rescan its plugin directories:

```bash
omarchy-shell shell rescanPlugins

```

Finally, enable the plugin through the CLI:

```bash
omarchy plugin enable my-plugin

```

This workflow, documented in [[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md#installing-a-third-party-plugin) (lines 89-91), bypasses the Git-based management while maintaining full compatibility with the manifest validation and IPC systems.

## Hot-Reloading and Development Workflow

Omarchy supports **hot-reloading** for plugin development. When an enabled plugin's files change, the shell automatically reloads that specific plugin's code without requiring a full shell restart. This behavior is verified by the test suite in [[`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/runtime-smoke-test.sh) (lines 53-55), which ensures that both built-in and user-installed plugins respond correctly to filesystem changes.

For developers, this means you can edit QML/JS files in `~/.config/omarchy/plugins/<id>/` and see changes immediately in the running shell, significantly accelerating the development cycle.

## Summary

- Third-party plugins live as **isolated Git repositories** under `~/.config/omarchy/plugins/`, each requiring a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) file declaring the plugin ID and kinds.
- Use **`omarchy plugin add <git-url>`** to clone repositories; plugins install in a **disabled state** for security auditing.
- Enable plugins explicitly with **`omarchy plugin enable <id>`** to activate them in the runtime registry.
- Update plugins safely using **`omarchy plugin update`**, which previews diffs before applying changes.
- For offline installation, copy directories manually and invoke **`omarchy-shell shell rescanPlugins`** to rebuild the registry.
- The **hot-reload** system automatically refreshes plugin code on file changes, supporting rapid development workflows.

## Frequently Asked Questions

### Where does Omarchy store third-party plugins?

Omarchy stores all user-installed plugins in the `~/.config/omarchy/plugins/` directory, with each plugin occupying a subdirectory named after its manifest `id`. The shell walks this directory at startup to build the runtime registry, as defined in the core documentation at [[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md).

### What fields are required in the plugin manifest.json?

The **[`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json)** file must reside at the repository root and declare at minimum the plugin's **`id`** (unique identifier) and **`kinds`** (array of types such as `bar`, `bar-widget`, or `panel`). Optional flags like `keepLoaded` control runtime lifecycle behavior. The validation logic ensures manifests are parsed correctly when the shell constructs its IPC registry.

### How does hot-reloading work for plugin development?

Omarchy monitors file changes within enabled plugin directories and automatically reloads the affected plugin's code without restarting the shell. This **hot-reloading** capability is tested in [[`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/runtime-smoke-test.sh) and applies equally to built-in plugins in `shell/plugins/**` and user-installed third-party extensions.

### Can I install Omarchy plugins without using Git?

Yes. While the CLI uses Git for the `omarchy plugin add` workflow, you can manually copy a plugin directory into `~/.config/omarchy/plugins/<id>/` and run `omarchy-shell shell rescanPlugins` to register it. This method supports offline installations, private repositories distributed as archives, or local development scenarios where Git remotes are not configured.