# How to Enable or Disable Plugins in Omarchy Using IPC

> Learn how to enable or disable Omarchy plugins easily using IPC. Control your plugins instantly with simple commands via the omarchy-shell CLI for a seamless workflow.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

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

```

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

```bash
omarchy-shell shell setPluginEnabled omarchy.clock "false"

```

Verify the call succeeded (returns `ok` on success):

```bash
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:

```bash

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

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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.