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

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

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:

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:

omarchy-shell shell reloadConfig

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

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

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

omarchy-shell shell listPlugins

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

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, 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 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.

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. Implementation details for the dispatcher can be found in shell/shell.qml.

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