# How to Apply Themes and Shell Configurations to the Omarchy Shell via IPC

> Learn to apply themes and shell configurations to Omarchy via IPC. Use the omarchy-shell command and verbs like setTheme or applyConfig for live updates without restarting.

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

---

**You can apply themes and shell configurations to the Omarchy shell via IPC by using the `omarchy-shell` command to send instructions to the `shell` IPC target, invoking verbs like `setTheme` for theme changes or `applyConfig` for live configuration updates without restarting the process.**

The Omarchy project (basecamp/omarchy) implements a desktop shell built on the Quickshell framework that runs as a long-lived process. According to the IPC contract documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) and implemented in `shell/shell.qml`, you can apply themes and shell configurations to the Omarchy shell via IPC, enabling instant visual and behavioral changes while the shell remains active.

## Understanding the IPC Architecture

The Omarchy shell exposes a single **`shell`** IPC target that serves as the central dispatcher for runtime state changes. This target is defined in the **IPC contract** located at [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) and implemented within `shell/shell.qml`.

When you execute `omarchy-shell`, you are communicating with this target to manipulate the active theme or adjust configuration parameters. The dispatcher parses your command and forwards it to the appropriate service modules, such as `shell/services/AppLibrary.qml`, which handles file operations for theme-related assets.

## Applying Themes via IPC

Themes in Omarchy correspond to directories under `~/.config/omarchy/themes/` or system-wide theme paths. The IPC layer allows you to switch themes instantly by updating the internal state and triggering a reload of colour palettes, icons, fonts, and generated configuration files.

### Using the CLI to Switch Themes

To change the active theme via IPC, use the **`setTheme`** verb followed by the theme name:

```bash
omarchy-shell shell setTheme "Tokyo Night"

```

Internally, this command writes the theme name to `~/.local/state/omarchy/current/theme/name` and triggers the shell to reload its visual assets. The implementation in `shell/services/AppLibrary.qml` handles the file operations, copying colour palettes and generating the necessary `*.toml` and `*.lua` files for compatible applications.

### Helper Scripts for Theme Management

For convenience, the repository provides **`bin/omarchy-theme-set`**, which wraps the IPC call:

```bash
omarchy-theme-set "Tokyo Night"

```

This script forwards the request to the IPC layer using the same `setTheme` verb, ensuring consistent behavior across manual invocations and automated scripts.

## Modifying Shell Configurations via IPC

Configuration files reside in `$OMARCHY_PATH/config/` and the user’s `~/.config/omarchy/` directory. The `shell` IPC target provides specific verbs for manipulating these settings without requiring a shell restart:

- **`reloadConfig`** – Re-reads all configuration files from disk and applies changes immediately.
- **`setConfig <json>`** – Replaces the entire effective configuration with the supplied JSON payload.
- **`applyConfig <json>`** – Performs a deep merge of the supplied JSON into the existing configuration.
- **`listPlugins`** – Returns a JSON array of loaded plugins, useful for verifying which configuration sections are active.
- **`setPluginEnabled <plugin-id> <true|false>`** – Toggles a specific plugin’s state, affecting its associated configuration handling.

### Live Configuration Examples

Refresh the shell after editing configuration files:

```bash
omarchy-shell shell reloadConfig

```

Apply a specific style change, such as adjusting bar opacity:

```bash
omarchy-shell shell applyConfig '{"bar":{"opacity":0.85}}'

```

List currently loaded plugins to identify which IPC handlers are available:

```bash
omarchy-shell shell listPlugins

```

Disable a plugin dynamically to prevent it from processing configuration changes:

```bash
omarchy-shell shell setPluginEnabled "notifications" false

```

## Why Use IPC for Theme and Config Changes

Leveraging IPC for shell customization provides distinct architectural advantages:

- **Zero-downtime updates** – The shell process remains alive while the UI updates instantly, preserving your session state.
- **Consistent API surface** – All CLIs, including `omarchy-theme-set`, `omarchy-menu`, and `omarchy-notification-send`, ultimately invoke the same IPC layer defined in `shell/shell.qml`, ensuring stable contracts across versions.
- **Fine-grained control** – You can target individual plugins via `setPluginEnabled` or manipulate specific configuration sections without affecting other shell components.

As documented in [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md), each first-party plugin registers its own IPC handlers, allowing you to enable or disable specific functionality after a theme change or configuration reload.

## Summary

- The **`shell`** IPC target in `shell/shell.qml` handles all theme and configuration requests for the Omarchy desktop environment.
- Use **`omarchy-shell shell setTheme "<name>"`** or the **`bin/omarchy-theme-set`** helper to switch themes instantly.
- Configuration changes use verbs like **`applyConfig`**, **`setConfig`**, and **`reloadConfig`** to update the shell without restarting.
- The IPC contract is formally documented in **[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)** and implemented through service modules like **`shell/services/AppLibrary.qml`**.
- Plugin-specific control is available via **`listPlugins`** and **`setPluginEnabled`**, allowing granular manipulation of shell capabilities.

## Frequently Asked Questions

### What IPC target handles theme and configuration changes in Omarchy?

The **`shell`** target handles these operations. It is the central dispatcher implemented in `shell/shell.qml` that processes verbs like `setTheme`, `applyConfig`, and `reloadConfig` according to the contract defined in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md).

### How do I change the Omarchy theme without restarting the shell?

Execute **`omarchy-shell shell setTheme "<theme-name>"`**. This updates `~/.local/state/omarchy/current/theme/name` and triggers an immediate reload of the colour palette, icons, and fonts via the `shell/services/AppLibrary.qml` service.

### Can I update specific configuration values without rewriting the entire config file?

Yes. Use the **`applyConfig`** verb with a JSON payload containing only the values you want to change. The shell performs a deep merge, updating only the specified keys while preserving the rest of your configuration.

### Where is the IPC contract documented in the repository?

The complete IPC specification, including available targets, verbs, and argument formats, is documented in **[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)**. Implementation details for the dispatcher can be found in **`shell/shell.qml`**.