How to Install a Third-Party Omarchy Plugin: Complete CLI Guide

You can install a third-party Omarchy plugin by running omarchy plugin add <git-url> to clone the repository into ~/.config/omarchy/plugins/<id>/, then activate it with omarchy plugin enable <id> after inspecting the manifest and source code.

Omarchy, the open-source desktop environment developed by Basecamp, extends its functionality through a plugin architecture that treats each extension as a standalone Git repository. Installing a third-party Omarchy plugin requires cloning the code locally, validating its manifest.json, and registering it with the running omarchy-shell. All plugin management logic resides in the basecamp/omarchy repository, specifically within the CLI wrappers located in bin/ and the runtime registry at shell/services/PluginRegistry.qml.

Prerequisites: The Plugin Manifest

Every valid third-party plugin must contain a manifest.json file at its repository root. This manifest declares the plugin's ID, available kinds (widget types), and entry points. Without this file, the omarchy plugin add command will reject the repository. The manifest format is documented in the Omarchy shell reference at docs/omarchy-shell.md lines 14-24.

Installing a Third-Party Omarchy Plugin from GitHub

Step 1: Add the Plugin Repository

Run the omarchy plugin add command followed by the Git URL:

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

According to the implementation in bin/omarchy-plugin-add, this command performs three actions:

• Clones the remote repository into ~/.config/omarchy/plugins/<id>/ (where <id> is extracted from the manifest)
• Validates the presence of manifest.json
• Registers the plugin with the shell's registry but keeps it disabled by default

Step 2: Review the Plugin Code

Before enabling any code execution, inspect the cloned directory:

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

Omarchy keeps newly added plugins disabled specifically to allow this security review. No widgets or scripts run until you explicitly enable the plugin.

Step 3: Enable the Plugin

Activate the plugin using its manifest ID:

omarchy plugin enable <id>

As implemented in bin/omarchy-plugin-enable, this updates the PluginRegistry.qml runtime registry, activates the specified kinds, and places bar widgets according to the manifest's default section configuration.

Automating Installation with Non-Interactive Mode

For CI/CD pipelines or automated setup scripts, bypass confirmation prompts by appending the --yes flag:

omarchy plugin add https://github.com/acme/omarchy-weather.git --yes
omarchy plugin enable acme.weather --yes

This non-interactive mode is documented in docs/omarchy-shell.md lines 86-89.

Manual Installation Without the CLI

You can install a third-party Omarchy plugin without using the omarchy plugin add command by manually placing the files:

1. Copy your prepared plugin folder to ~/.config/omarchy/plugins/<id>/
2. Run omarchy-shell shell rescanPlugins to refresh the registry
3. Execute omarchy plugin enable <id> to activate it

This manual workflow mirrors the automated flow but requires you to handle the initial file placement and validation yourself.

Managing Installed Plugins

Updating Plugins

Fetch the latest changes for all installed plugins with:

omarchy plugin update

The bin/omarchy-plugin-update wrapper performs a fast-forward pull and displays a diff of changes before applying them, allowing you to review modifications before they take effect.

Removing Plugins

To completely remove a third-party Omarchy plugin:

omarchy plugin remove <id>

This deletes the directory at ~/.config/omarchy/plugins/<id>/ and removes its entry from the registry, as implemented in bin/omarchy-plugin-remove.

Summary

• Third-party plugins are standalone Git repositories containing a root-level manifest.json file
• Installation uses omarchy plugin add <url> to clone into ~/.config/omarchy/plugins/<id>/
• Security default: Plugins remain disabled after cloning to allow code review before activation
• Activation requires omarchy plugin enable <id> to register with shell/services/PluginRegistry.qml
• Automation is supported via the --yes flag for non-interactive environments
• Updates show a diff before fast-forwarding via omarchy plugin update

Frequently Asked Questions

Where are third-party Omarchy plugins stored on disk?

Third-party plugins are cloned into ~/.config/omarchy/plugins/<id>/, where <id> corresponds to the identifier declared in the plugin's manifest.json. The omarchy plugin add command handles this directory creation automatically.

Why does Omarchy disable plugins by default after installation?

Omarchy disables newly added plugins as a security measure. This prevents malicious or buggy code from executing immediately upon cloning. You must explicitly run omarchy plugin enable <id> after reviewing the source files, giving you full control over what runs in your desktop environment.

How do I update a third-party Omarchy plugin to the latest version?

Run omarchy plugin update to fetch the latest commits from the plugin's remote repository. The command displays a diff of changes before applying a fast-forward pull, ensuring you can review updates before they become active. This is handled by the bin/omarchy-plugin-update script.

Can I install an Omarchy plugin without internet access or the CLI?

Yes. You can manually copy a plugin directory into ~/.config/omarchy/plugins/<id>/, then run omarchy-shell shell rescanPlugins to force the shell to discover the new manifest, followed by omarchy plugin enable <id> to activate it. This manual method bypasses the Git cloning performed by omarchy plugin add.

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