How to Enable a Plugin Using Omarchy’s IPC setPluginEnabled Method

Call omarchy-shell shell setPluginEnabled <plugin-id> "true" to toggle a plugin on, or use the omarchy-plugin-enable wrapper; only the literal string "true" enables the plugin, while any other value disables it.

Omarchy’s desktop environment runs on a persistent Quickshell instance (omarchy-shell) that exposes an IPC interface for runtime configuration. To enable a plugin using Omarchy’s IPC setPluginEnabled method, you invoke a command against the running shell process, which delegates state management to the internal PluginRegistry and persists changes to shell.json.

Understanding the IPC setPluginEnabled Method Signature

The IPC method follows this signature:

setPluginEnabled <id> <"true"|…>

• id – The plugin’s identifier (e.g., omarchy.clock or community.weather-extra).
• enabled – A string value; only the literal "true" activates the plugin. Any other string—including "false"—disables it.

The method returns "ok" on success or "unknown" if the plugin ID is not recognized.

Enabling Plugins via the setPluginEnabled IPC Command

You can enable plugins directly through the IPC interface or use a convenience wrapper.

Direct IPC Invocation with omarchy-shell

Use the omarchy-shell command to call the method directly:

omarchy-shell shell setPluginEnabled omarchy.clock true

Expected output:

ok

To disable the plugin, pass any value other than "true":

omarchy-shell shell setPluginEnabled omarchy.clock false

Using the omarchy-plugin-enable Helper

For convenience, Omarchy provides omarchy-plugin-enable, which wraps the IPC call:

omarchy-plugin-enable omarchy.clock

Internally, this executes:

omarchy-shell shell setPluginEnabled "$id" true

This helper is defined in bin/omarchy-plugin-enable.

Programmatic setPluginEnabled Usage in Scripts

For automation, use the shell_ipc function to capture results:

result=$(shell_ipc shell setPluginEnabled "community.weather-extra" "true")
if [[ $result == ok ]]; then
    echo "Weather plugin enabled"
else
    echo "Failed to enable plugin: $result"
fi

This pattern is useful for installation scripts that need to verify plugin state before proceeding.

Internal Implementation of setPluginEnabled

According to the basecamp/omarchy source code, the IPC method is defined in shell/shell.qml at lines 907‑909:

function setPluginEnabled(id: string, enabled: string): string {
    return shell.pluginRegistry.setEnabled(id, enabled === "true") ? "ok" : "unknown"
}

This function forwards the request to shell.pluginRegistry.setEnabled(), which:

1. Updates the persisted state in shell.json
2. Emits the appropriate signals to trigger UI updates

The concrete logic for setEnabled resides in shell/services/PluginRegistry.qml, where the function mutates the plugin state and handles placement options.

Summary

• The setPluginEnabled IPC method requires a plugin ID and a string value; only "true" enables the plugin.
• Use omarchy-shell shell setPluginEnabled <id> true for direct activation or omarchy-plugin-enable <id> for convenience.
• The method returns "ok" on success and "unknown" if the plugin ID does not exist.
• State changes persist immediately to shell.json via the PluginRegistry service.

Frequently Asked Questions

What happens if I pass "false" to setPluginEnabled?

Passing "false"—or any string other than "true"—disables the plugin. The implementation in shell/shell.qml explicitly checks enabled === "true", so only that exact literal activates the plugin; all other values evaluate to disabled.

Can I use setPluginEnabled to toggle system plugins?

Yes, you can use the method on any plugin registered with the PluginRegistry, including core system plugins like omarchy.clock or community plugins like community.weather-extra, provided you know the exact plugin ID.

Where is the plugin state saved when I enable it?

The PluginRegistry persists the enabled state to shell.json immediately upon invocation. According to the source code in shell/services/PluginRegistry.qml, the setEnabled function updates this configuration file and emits signals to notify the running shell of state changes.

Is there a way to check if a plugin is enabled before calling setPluginEnabled?

While the setPluginEnabled method only toggles state and returns "ok" or "unknown", you can query the current plugin state by examining shell.json directly or using other IPC methods documented in [docs/omarchy-shell.md](https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md) to list active plugins before making changes.

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