How to Remove an Omarchy Plugin: CLI and Manual Methods

You can remove an Omarchy plugin by running the omarchy plugin remove <plugin-id> command or manually deleting the plugin directory from ~/.config/omarchy/plugins/ followed by a registry rescan.

Omarchy, the open-source system developed by Basecamp, treats each plugin as a self-contained directory managed by the PluginRegistry service. When you remove an Omarchy plugin, the system must clean up both the filesystem checkout and the internal registry that tracks enabled features. You have two supported approaches to accomplish this, depending on whether you prefer automated cleanup or manual control.

Method 1: Using the Built-in CLI Command (Recommended)

The omarchy CLI provides the safest way to remove an Omarchy plugin because it automatically updates the registry and user configuration. According to the documentation in docs/omarchy-shell.md, the remove command handles the complete lifecycle cleanup.

Run the following command to remove a specific plugin:

omarchy plugin remove <plugin-id>

For example, to remove a third-party weather plugin:

omarchy plugin remove acme.weather

This command performs three critical actions:

1. Deletes the plugin checkout located at ~/.config/omarchy/plugins/<plugin-id>/.
2. Removes registry entries from ~/.config/omarchy/shell.json, including any bar widget layouts associated with the plugin.
3. Triggers a hot-reload by invoking omarchy-shell shell rescanPlugins, which updates the running shell without requiring a restart.

The PluginRegistry service defined in shell/services/PluginRegistry.qml processes the rescan command, validating that the plugin directory no longer exists and updating the available plugin list accordingly.

Method 2: Manual Plugin Removal Without the CLI

If the CLI is unavailable or you need to perform cleanup operations, you can manually remove an Omarchy plugin by deleting its directory and refreshing the registry.

First, delete the plugin directory:

rm -rf ~/.config/omarchy/plugins/<plugin-id>

Next, trigger a registry rescan to update the running system:

omarchy-shell shell rescanPlugins

If the plugin had custom entries in your user configuration—such as bar widgets or key bindings—you must manually edit ~/.config/omarchy/shell.json to remove the corresponding objects. The default/agents/skills/omarchy/plugins.md file explains that this JSON structure records enabled plugins and their layout positions, and orphaned entries will not harm the system but may generate warnings in the logs.

Understanding the PluginRegistry and Configuration Structure

The removal process relies on the PluginRegistry service implemented in shell/services/PluginRegistry.qml. This service handles discovery, validation, and hot-reloading of all plugins found in ~/.config/omarchy/plugins/. When you run the rescanPlugins command or use the CLI remove workflow, the registry:

• Scans the plugins directory for valid plugin manifests.
• Compares the filesystem state against the enabled list in ~/.config/omarchy/shell.json.
• Removes references to plugins that no longer exist on disk.
• Signals the shell to update its internal component tree without restarting the session.

The docs/omarchy-shell.md reference documents this behavior in the plugin lifecycle section, noting that the registry maintains the separation between installed plugins (directories on disk) and enabled plugins (entries in shell.json).

Summary

• Use the CLI command omarchy plugin remove <plugin-id> to automatically delete the plugin directory, clean up shell.json, and trigger a hot-reload via the PluginRegistry.
• Manual removal requires deleting ~/.config/omarchy/plugins/<plugin-id>/ and running omarchy-shell shell rescanPlugins, plus editing ~/.config/omarchy/shell.json if the plugin had custom layout entries.
• The PluginRegistry in shell/services/PluginRegistry.qml manages plugin discovery and handles the rescan operation that updates the running shell state.
• Plugins are stored as self-contained directories, so removal is simply a matter of filesystem cleanup followed by registry synchronization.

Frequently Asked Questions

Where are Omarchy plugins stored on disk?

Omarchy plugins live in individual directories under ~/.config/omarchy/plugins/<plugin-id>/. Each plugin contains its own manifest, QML files, and resources. The PluginRegistry scans this location at startup and during rescan operations to build the available plugin list.

What happens if I delete a plugin directory without running the rescan command?

If you manually delete ~/.config/omarchy/plugins/<plugin-id>/ without running omarchy-shell shell rescanPlugins, the PluginRegistry may continue to reference the plugin in memory until the next rescan or restart. The system will log warnings about missing files, but it will not crash. Running the rescan command or restarting Omarchy clears these stale references.

Can I disable an Omarchy plugin instead of removing it?

Yes. Disabling a plugin toggles its entry in ~/.config/omarchy/shell.json without deleting the directory in ~/.config/omarchy/plugins/. This allows you to quickly re-enable the plugin later without re-downloading or reinstalling files. Removal, conversely, deletes the checkout entirely and requires re-installation to use the plugin again.

How does the PluginRegistry handle plugin validation during a rescan?

The PluginRegistry service validates each directory in ~/.config/omarchy/plugins/ by checking for required manifest files and valid QML components. If a directory is missing or corrupted—as happens after manual deletion—the registry marks it as unavailable and removes it from the active plugin list. This validation logic is implemented in shell/services/PluginRegistry.qml and operates automatically during the rescanPlugins IPC call.

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