How Theming Is Managed in Omarchy

Omarchy manages theming through a decoupled architecture where TOML-based color definitions in themes/*/colors.toml are injected into QML template files using {{ variable }} placeholders, then processed by CLI commands like omarchy-theme-set-templates and omarchy-theme-apply to generate the active desktop configuration.

The open-source Omarchy desktop environment by Basecamp implements a strict separation between theme data and presentation logic. According to the basecamp/omarchy source code, the theming system relies on plain-text configuration files and template processing to render user-specific desktop environments without requiring direct QML manipulation.

Core Architecture of Omarchy Themes

Omarchy's theming system consists of four primary components that operate together to render the final desktop appearance.

Color Definitions in TOML

Theme palettes are defined in plain-text TOML files located at themes/*/colors.toml within the repository. These files specify the complete color palette including accent colors, background, foreground, and the full spectrum of bright and muted variants. For example, the bundled Catppuccin theme stores its palette in themes/catppuccin/colors.toml.

Template Files with Variable Placeholders

Presentation logic resides in default/themed/*.tpl files containing QML or other markup snippets with {{ variable }} placeholders. These templates serve as blueprints that get populated with color values during the rendering process. The separation allows the same structural templates to generate different visual appearances based solely on the TOML color data.

Runtime Helper Commands

The system provides specific CLI utilities to process and activate themes:

• omarchy-theme-set-templates: Reads a theme's colors.toml and substitutes values into all *.tpl files under default/themed/, writing the rendered output to the user config directory.
• omarchy-theme-apply: Activates the rendered theme in the running desktop environment and signals the shell to reload its configuration.
• omarchy-theme-set-colors: Directly updates color values in the active configuration without reprocessing templates.
• omarchy-theme-list: Displays available themes containing valid colors.toml files.

User-Level Configuration and Assets

Rendered themes and user overrides are stored in ~/.config/omarchy/themes/<theme-name>/. Users may override any theme component by placing modified files in the corresponding relative path within their home directory. Additionally, themes may bundle optional themes/*/background.png images for desktop backgrounds or custom fonts referenced in default/fonts/omarchy/README.md.

Theming Workflow and Template Rendering

The process of applying or creating themes follows a predictable pipeline that bridges the gap between source definitions and the running desktop environment.

First, the system locates the theme's colors.toml file. Then omarchy-theme-set-templates <theme-name> processes every *.tpl template in default/themed/, replacing {{ variable }} placeholders with corresponding hex values from the TOML file. Finally, omarchy-theme-apply <theme-name> copies these rendered files into ~/.config/omarchy/ and refreshes the UI.

Creating and Customizing Omarchy Themes

You can create custom themes by duplicating an existing color definition and modifying the values, then regenerating the templates.

# List all available themes with valid colors.toml files

omarchy-theme-list

# Apply the built-in catppuccin theme immediately

omarchy-theme-apply catppuccin

# Create a custom theme called "my-dark"

mkdir -p ~/.config/omarchy/themes/my-dark
cp ~/.config/omarchy/themes/catppuccin/colors.toml \
   ~/.config/omarchy/themes/my-dark/

# Edit the color values to your preference

nano ~/.config/omarchy/themes/my-dark/colors.toml

# Render templates with your new color values

omarchy-theme-set-templates my-dark

# Apply the rendered theme to the desktop

omarchy-theme-apply my-dark

Key Source Files and Documentation

Several files in the basecamp/omarchy repository define and document this behavior:

• docs/theming.md: Comprehensive documentation of the theme/template workflow.
• default/agents/skills/omarchy/theming.md: Concrete step-by-step instructions for theme creation and customization.
• default/agents/skills/omarchy/SKILL.md: References theming documentation as a core system skill.
• docs/omarchy-shell.md: Documents the helper commands including omarchy-theme-set-templates and omarchy-theme-apply.
• default/themed/*.tpl: Source template files containing the {{ variable }} placeholder syntax.
• themes/*/colors.toml: Canonical color definitions for all bundled themes.

Summary

• TOML-based palettes: Colors are defined in themes/*/colors.toml files separate from presentation code.
• Template injection: The *.tpl files in default/themed/ use {{ variable }} syntax to receive color values dynamically.
• CLI-driven workflow: Commands like omarchy-theme-set-templates and omarchy-theme-apply handle rendering and activation without manual file copying.
• User overrides: Customizations belong in ~/.config/omarchy/themes/ and take precedence over system defaults.
• Asset support: Themes can bundle backgrounds at themes/*/background.png and custom font configurations.

Frequently Asked Questions

Where are theme colors defined in Omarchy?

Theme colors are defined in plain-text TOML files located at themes/*/colors.toml in the repository, or ~/.config/omarchy/themes/<name>/colors.toml for user themes. Each file contains hex color values for accents, backgrounds, foregrounds, and bright/muted variants.

How do I apply a custom theme without editing QML files?

Run omarchy-theme-set-templates <theme-name> to process the QML templates with your color definitions, then execute omarchy-theme-apply <theme-name> to activate it. This workflow injects TOML values into the {{ variable }} placeholders automatically, requiring no manual QML editing.

What is the purpose of the *.tpl files in the default/themed directory?

These files contain markup templates with placeholder variables like {{ accent }} or {{ background }}. The omarchy-theme-set-templates command renders these into final configuration files by substituting placeholders with values from the active theme's colors.toml, as documented in docs/theming.md.

Can I override specific theme components for my user only?

Yes. Place modified files in ~/.config/omarchy/themes/<theme-name>/ following the same relative paths as the source repository. The system prioritizes user-level configurations in ~/.config/omarchy/, allowing you to override colors, fonts, or individual templates without affecting the system-wide installation.

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