Omarchy Theming Architecture Components: A Complete Technical Guide

Omarchy's theming architecture consists of theme directories, a colors.toml palette, template files, generated configs, runtime hooks, and a QML border API that work together to produce a unified desktop theme.

Omarchy's theming system is built around a clear hierarchy of files and runtime steps that transform a simple color palette into a fully featured desktop environment. This architecture enables single-source color management, user-level customization, and safe third-party theme installation. Understanding these components helps developers and power users customize their Omarchy installation effectively.

Theme Directories and Storage Locations

Themes reside in two distinct locations based on ownership and scope.

System themes live under /usr/share/omarchy/themes/ with individual themes in subdirectories like themes/<name>/. These ship with Omarchy and serve as the foundation for all theme operations.

User themes occupy ~/.config/omarchy/themes/<name>/. This directory allows personal themes and overrides without modifying system files. The separation ensures upgrades preserve customizations.

According to the Omarchy source code at [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L3-L5), this dual-path design enables overlay-based theme construction where user files augment or replace system defaults.

The colors.toml Color Palette

The canonical color definition file sits at the heart of every theme. The colors.toml file defines semantic keys that all templates consume:

• accent — primary interactive color
• background — main surface color
• foreground — text and icon color
• Additional semantic keys for specific UI roles

This single source of truth eliminates color drift across components. When a theme author updates accent, every template referencing {{ accent }} receives the new value upon regeneration.

The palette structure is documented in [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L68-L93) and serves as the input for all downstream template rendering.

Template Files and Rendering Engine

Templates are plain-text files containing {{ key }} placeholders that the rendering engine substitutes with values from colors.toml.

Built-in templates reside in default/themed/*.tpl. These ship with Omarchy and cover core components:

Template	Output
shell.toml.tpl	shell.toml for shell configuration
hyprland.lua.tpl	hyprland.lua for window manager settings

User templates can be added to ~/.config/omarchy/themed/*.tpl for custom components. This extensibility allows third-party applications to participate in the theming system without modifying core files.

The omarchy-theme-set-templates command performs the actual rendering, as referenced in bin/omarchy-theme-set-templates.

Generated Configuration Files

Template rendering produces concrete configuration files that applications consume directly:

• shell.toml — shell appearance and behavior
• hyprland.lua — Hyprland window manager theming
• Terminal emulator configs (colormaps and cursor styles)
• Editor configurations (VS Code vscode.json)

Hand-written overrides bypass the template system entirely. Files like shell.lock.toml replace specific sections of generated output. This hybrid approach supports complex cases where template logic proves insufficient.

The generation process and override behavior are detailed in [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L78-L88).

Additional Theme Assets

Themes optionally bundle visual and input resources:

• backgrounds/ — wallpaper images
• preview.png — thumbnail for theme selectors
• icons.theme — icon theme reference
• keyboard.rgb — keyboard LED color profiles
• unlock.png — lock screen background
• light.mode marker — indicates light theme variant

These files are copied or symlinked into the active theme location during activation. Their presence is optional; themes function with only colors.toml and templates.

Theme Activation Flow

The omarchy-theme-set <name> command orchestrates theme application through five distinct stages:

1. Stage — Create clean directory at ~/.local/state/omarchy/current/next-theme
2. Overlay — Copy system theme, then apply user override files
3. Generate — Produce colors.toml from terminal configs if palette missing
4. Render — Execute omarchy-theme-set-templates to process all *.tpl files
5. Activate — Move result to active location and trigger theme-set hook

This atomic staging prevents partial theme application. If any stage fails, the current theme remains intact.

The complete flow is implemented in bin/omarchy-theme-set.

Runtime Hooks for Live Application

After activation, Omarchy executes hook scripts matching ~/.config/omarchy/hooks/theme-set*. These scripts propagate theme changes to running applications:

• Restart compositor or shell components
• Send retint signals to supported applications
• Update status bars and notification daemons

The hook system decouples theming from application-specific update logic. Application maintainers provide hooks rather than modifying core theme code.

Hook conventions are documented in [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L40-L45).

QML Border API for Shell Rendering

The QML border API provides programmatic access to theme-aware border specifications:

• Border.surfaceSpec — borders for background surfaces
• Border.controlSpec — borders for interactive controls
• Border.flat — flat style indicator

These specifications respect the active palette, producing solid colors or gradients derived from colors.toml. Shell code uses these APIs rather than hardcoding colors, ensuring visual consistency.

The API surface is described in [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L22-L25).

Security: Theme Installation Denylist

Omarchy implements defensive filtering when installing themes from remote git repositories. The INSTALLED_THEME_DENIED logic in bin/omarchy-theme-set restricts which files enter the staging directory:

• Allowed: *.lua, terminal configs, vscode.json, symlinks
• Denied: All other files, especially executable scripts

This security boundary ensures that colors.toml and templates remain the only inputs to generated configs. Malicious themes cannot inject arbitrary code—only color values and template logic execute.

The denylist implementation appears in [docs/theming.md](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L48-L60).

Practical Usage Examples

Activate a built-in theme:

omarchy-theme-set catppuccin

Re-render templates after manual colors.toml edit:

omarchy-theme-set-templates

Create a custom lock screen override:

cat > ~/.config/omarchy/themes/mytheme/shell.lock.toml <<'EOF'
text        = "#ffffff"
placeholder = "#444444"
border      = "#ff00ff"
EOF
omarchy-theme-set mytheme

Key Files in the Architecture

Path	Purpose
docs/theming.md	Comprehensive design documentation
bin/omarchy-theme-set	Core theme activation command
bin/omarchy-theme-set-templates	Template rendering engine
default/themed/*.tpl	Built-in template collection
themes/*/colors.toml	Built-in theme palettes
~/.config/omarchy/hooks/theme-set*	Post-activation hook scripts

Summary

• Single source of truth: colors.toml centralizes all color definitions
• Template-driven generation: *.tpl files produce consistent configs across components
• User overlay system: Personal themes extend system defaults without modification
• Atomic activation: Five-stage omarchy-theme-set flow prevents partial states
• Hook-based propagation: Runtime scripts update running applications
• Security boundaries: Installation denylist blocks executable code from remote themes

Frequently Asked Questions

How do I create a custom Omarchy theme from scratch?

Create a directory at ~/.config/omarchy/themes/yourname/ containing colors.toml with your palette and any template overrides in themed/*.tpl. Run omarchy-theme-set yourname to activate. The command copies your files over the system defaults, renders templates, and fires hooks.

Why does Omarchy use templates instead of direct config files?

Templates ensure color consistency across dozens of configuration files. When accent changes in colors.toml, every template referencing {{ accent }} updates automatically. Without templates, manual synchronization across shell, terminal, editor, and WM configs would be error-prone.

What happens if I edit a generated file directly?

Direct edits to generated files like shell.toml are overwritten on next theme activation. Persist changes by creating an override file (e.g., shell.lock.toml) or modifying the source template. The .lock.toml suffix signals Omarchy to use your version instead of the generated one.

Can I use themes from untrusted Git repositories safely?

Yes, within limits. The INSTALLED_THEME_DENIED filter in bin/omarchy-theme-set strips all files except *.lua, terminal configs, vscode.json, and symlinks. Executable scripts and arbitrary binaries never reach the staging directory. However, review colors.toml and templates for malicious Lua code before activation.

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