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

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) 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 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/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.

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

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:

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:

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:

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

Then force the shell to rescan its plugin directories:

omarchy-shell shell rescanPlugins

Finally, enable the plugin through the CLI:

omarchy plugin enable my-plugin

This workflow, documented in [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/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 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/quattro/docs/omarchy-shell.md).

What fields are required in the plugin manifest.json?

The 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/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.

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