How to Enable or Disable Plugins in Omarchy Using IPC

TLDR: Use the omarchy-shell CLI to send setPluginEnabled <plugin-id> "true" or "false" via IPC to the running Quickshell process, which instantly updates ~/.config/omarchy/shell.json without requiring a desktop restart.

Omarchy’s desktop environment runs as a single long‑living Quickshell process (omarchy-shell) that manages all plugins through an inter‑process communication (IPC) contract. According to the basecamp/omarchy source code, the canonical way to enable or disable plugins in Omarchy using IPC is through the setPluginEnabled method exposed by the shell’s PluginRegistry.

The IPC Architecture and PluginRegistry

All CLI commands communicate with the active shell through IPC targets defined in docs/omarchy-shell.md. When you invoke a command, the shell forwards the request to the QML PluginRegistry object located in shell/services/PluginRegistry.qml. This registry maintains the authoritative state of which plugins (bar widgets, panels, overlays, or services) are currently active.

The registry’s setEnabled function handles the actual logic: it validates the plugin ID, invokes shellConfigMutator to update the in‑memory representation of shell.json, persists the change to ~/.config/omarchy/shell.json, and triggers a hot‑reload so the UI updates immediately.

The setPluginEnabled IPC Method

Command Syntax

The IPC command follows this strict format:

omarchy-shell shell setPluginEnabled <plugin-id> "<true|false>"

• <plugin-id>: The unique identifier of the plugin (e.g., omarchy.clock or community.weather-extra).
• "true" or "false": The enabled flag as a string literal. Only the exact string "true" enables the plugin; any other value (including "false") disables it. This preserves type‑stability because IPC arguments are strings only.

Implementation Flow

When you execute the command, the shell processes the request through these steps:

1. IPC Target Exposure: The shell process exposes the setPluginEnabled method through its IPC interface, as documented in docs/omarchy-shell.md.
2. Method Mapping: The shell maps the IPC call to PluginRegistry.setEnabled inside shell/services/PluginRegistry.qml (lines 49–52).
3. String Parsing: The registry checks the enabled argument. The literal string "true" activates the plugin; all other strings deactivate it.
4. Configuration Mutation: The registry calls shellConfigMutator to modify the appropriate entry in the in‑memory shell.json representation, then writes the file to disk.
5. Hot Reload: The shell watches ~/.config/omarchy/shell.json for changes. Upon detecting the mutation, it instantly adds or removes the plugin from the UI without restarting the entire desktop environment.

Practical CLI Examples

Direct IPC Commands

Enable a third‑party plugin:

omarchy-shell shell setPluginEnabled community.weather-extra "true"

Disable a built‑in bar widget such as the clock:

omarchy-shell shell setPluginEnabled omarchy.clock "false"

Verify the call succeeded (returns ok on success):

omarchy-shell shell call setPluginEnabled omarchy.clock "true"

# => ok

Using the omarchy Wrapper CLI

For convenience, Omarchy provides a higher‑level omarchy CLI that internally invokes the same IPC method:

# Enable via the user-friendly CLI

omarchy plugin enable community.weather-extra

# Disable via the CLI

omarchy plugin disable omarchy.clock

These commands abstract the string literal requirements and error handling while targeting the same setPluginEnabled IPC endpoint.

Scripting Plugin Toggles

Automate plugin state changes in shell scripts:

PLUGIN_ID="omarchy.power"
CURRENT=$(omarchy-shell shell call setPluginEnabled "$PLUGIN_ID" "true")
if [[ $CURRENT == "ok" ]]; then
    echo "Plugin $PLUGIN_ID is now enabled"
else
    echo "Failed to enable $PLUGIN_ID"
fi

Configuration Persistence and Hot Reload

All plugin state changes persist to ~/.config/omarchy/shell.json. Because the shell monitors this file for modifications, changes take effect immediately. You do not need to log out or restart the Quickshell process. This architecture is implemented in shell/services/PluginRegistry.qml (lines 14–16) and documented in shell/README.md.

Summary

• IPC Command: Use omarchy-shell shell setPluginEnabled <id> "true" to enable or "false" to disable.
• Core File: shell/services/PluginRegistry.qml contains the setEnabled logic that processes your request.
• String Literals: Always pass "true" as a quoted string; boolean literals are not accepted.
• Persistence: Changes write to ~/.config/omarchy/shell.json and hot‑reload instantly.
• Abstractions: The omarchy plugin enable/disable commands wrap the raw IPC calls for easier scripting.

Frequently Asked Questions

What is the exact IPC command format to toggle a plugin?

The exact format is omarchy-shell shell setPluginEnabled <plugin-id> "<true|false>". The enabled flag must be the literal string "true" to activate the plugin; any other string value disables it. This format is required because the IPC transport only accepts string arguments.

Where does Omarchy store the enabled or disabled state of plugins?

The state persists in ~/.config/omarchy/shell.json. When you send the IPC command, the PluginRegistry in shell/services/PluginRegistry.qml invokes shellConfigMutator to update this file and then triggers a hot reload.

Do I need to restart Omarchy after enabling or disabling a plugin via IPC?

No. The shell process monitors ~/.config/omarchy/shell.json for changes. Once the setPluginEnabled method updates the configuration, the shell hot‑reloads the file and immediately adds or removes the plugin from the UI without restarting the desktop.

Can I use shell scripts to programmatically toggle plugins?

Yes. You can script the omarchy-shell shell call setPluginEnabled command and check for the ok response to confirm success. For simpler automation, use the omarchy plugin enable and omarchy plugin disable wrappers, which handle the IPC communication internally and return appropriate exit codes.

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