How to Apply a Theme to the Omarchy Shell

To apply a theme to the Omarchy shell, use the omarchy-theme-set utility to base64-encode the theme's colors.toml and shell.toml files and transmit them via the applyTheme IPC command, which updates the interface instantly without requiring a shell restart.

Omarchy is a desktop shell environment where visual styling is controlled through TOML configuration files. When you apply a theme to the Omarchy shell, the system decodes base64-encoded payloads and injects them into the running QML interface through an IPC layer. This architectural design allows zero-downtime theme switching while preserving active applications and window states.

Theme File Structure and Location

Every theme resides in a subdirectory under themes/ and requires two specific TOML files:

• colors.toml – Defines the color palette including foreground, background, and accent values.
• shell.toml – Configures shell-specific settings such as bar transparency, widget placement, and font tokens.

These files serve as the source of truth for the Color module, which parses them at runtime to update the interface.

The IPC-Based Theme Application Architecture

When you initiate a theme change, the shell follows a strict IPC pipeline to ensure atomic updates. According to the Omarchy source code, the process works as follows:

1. Encoding: The colors.toml and shell.toml files are base64-encoded into strings.
2. Transmission: The encoded payloads are sent via the applyTheme IPC command.
3. Decoding and Loading: In shell/shell.qml, the applyTheme handler decodes the strings and invokes Color.loadColors() and Color.loadShell().
4. UI Refresh: The system calls Style.scheduleRefresh() to repaint affected components without restarting the shell session.

This flow ensures that when you apply a theme to the Omarchy shell, the transition is instantaneous and non-destructive.

Three Methods to Apply a Theme

You can apply a theme using the provided CLI wrapper, manual IPC commands, or programmatic QML calls.

Method 1: Using the CLI Helper (Recommended)

The bin/omarchy-theme-set wrapper automates base64 encoding and IPC transmission. Located at bin/omarchy-theme-set, this script handles the heavy lifting around lines 112-129.

To apply a theme:

omarchy-theme-set solitude

The script locates themes/solitude/colors.toml and themes/solitude/shell.toml, encodes them, and dispatches the applyTheme command automatically.

Method 2: Manual Base64 Encoding and IPC

For advanced use cases or custom theme paths, manually encode the files and invoke the IPC command directly:

# Encode theme files as base64 (wrap=0 for single-line strings)

colors_b64=$(base64 -w0 themes/solitude/colors.toml)
shell_b64=$(base64 -w0 themes/solitude/shell.toml)

# Send via omarchy-shell IPC

omarchy-shell applyTheme "$colors_b64" "$shell_b64"

This bypasses the helper script and sends raw payloads directly to the shell's IPC handler at shell/shell.qml.

Method 3: Programmatic Application from QML

Within the shell's QML environment, trigger theme changes using the shell_ipc object:

// Inside any QML component with shell_ipc access
shell_ipc.shell.applyTheme(colorsBase64, shellBase64)

This method integrates theme switching directly into custom widgets or settings panels, referencing the same applyTheme logic implemented in the core shell.

Key Source Files and Functions

File	Role	Key Functions
shell/shell.qml	IPC handler for applyTheme command	Decodes base64, calls Color.loadColors() and Color.loadShell(), triggers Style.scheduleRefresh()
shell/Commons/Color.qml	Theme state management	loadColors(), loadShell(), stores config in currentThemePath
bin/omarchy-theme-set	CLI automation	Encodes TOML files and invokes IPC (lines 112-129)
[docs/omarchy-shell.md](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md)	Command reference	Documents applyTheme parameters and usage

Summary

Applying a theme to the Omarchy shell involves encoding TOML configuration files and transmitting them through the IPC layer. Key takeaways include:

• Theme Structure: Every theme requires colors.toml and shell.toml in a themes/<name>/ directory.
• IPC Command: The applyTheme command accepts base64-encoded strings and processes them in shell/shell.qml (lines 879-887).
• Zero-Downtime Updates: The Color module parses themes and refreshes the UI via Style.scheduleRefresh() without restarting the shell.
• CLI Convenience: Use omarchy-theme-set <theme-name> for automated application, or manually encode files and call omarchy-shell applyTheme for custom implementations.

Frequently Asked Questions

Do I need to restart the Omarchy shell after applying a theme?

No. The Omarchy shell applies themes dynamically through its IPC layer. When you send the applyTheme command, the shell immediately decodes the base64 payloads, parses the TOML configuration via Color.loadColors() and Color.loadShell(), and schedules a UI refresh. Your applications and window states remain intact throughout the process.

What files are required to apply a theme to the Omarchy shell?

Every valid theme requires exactly two TOML files located in themes/<theme-name>/: colors.toml for the palette definitions and shell.toml for layout and transparency settings. Both files must be base64-encoded and sent together via the applyTheme IPC command to ensure consistent styling.

Can I apply a theme from a custom directory outside of themes/?

Yes. While the omarchy-theme-set helper looks in the standard themes/ directory, you can apply a theme from any location by manually base64-encoding your colors.toml and shell.toml files and passing them as arguments to omarchy-shell applyTheme. This allows testing themes without moving them into the system themes folder.

Where is the active theme configuration stored after application?

The active theme configuration is stored in memory by the Color module, specifically in the currentThemePath property defined in shell/Commons/Color.qml. The shell does not write the applied theme back to disk; it maintains the parsed TOML values in runtime memory for the UI to reference via QML property bindings.

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