# Omarchy Theme Activation Flow: How the 11-Step Process Works

> Discover the Omarchy theme activation flow. Learn how this 11-step process stages, renders, and atomically swaps themes, updating your shell instantly.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-03

---

**The Omarchy theme activation flow is a 11-step pipeline that stages themes in `~/.local/state/omarchy/current/next-theme`, renders templates from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), atomically swaps the current theme, and notifies the running shell via IPC.**

Omarchy's theme system handles everything from built-in themes to user-installed Git repositories through a carefully orchestrated activation pipeline. This guide breaks down the complete **Omarchy theme activation flow** using actual source paths and implementation details from the `omacom/omarchy` repository.

## Entry Point: The `omarchy-theme-set` Command

Theme activation begins with the CLI command:

```bash
omarchy theme set "<theme-name>"

```

The `bin/omarchy-theme-set` script serves as the main entry point. It performs initial validation, resolves the theme directory, and acquires a filesystem lock to prevent race conditions during concurrent theme changes.

Key validation happens at **lines 64-66**, where the script ensures only one theme change proceeds at a time.

## Staging Area Preparation

A clean **staging directory** is created at `~/.local/state/omarchy/current/next-theme`. This directory holds the *next* theme before it replaces the current one, ensuring atomic deployment.

```bash

# The staging path is constructed as

~/.local/state/omarchy/current/next-theme

```

This approach keeps the current session stable while the new theme is assembled.

## Theme Assembly: Base Copy and User Overlay

The activation flow merges theme sources in two phases:

### 1. Base Theme Copy

The official theme copies from the repository-wide location:

```bash
$OMARCHY_PATH/themes/<name>/

```

Implementation at **lines 68-70** of `omarchy-theme-set`.

### 2. User Theme Overlay

The script handles two overlay cases differently:

- **Hand-written directory**: Copied wholesale with no filtering
- **Git-installed repository**: Walked with **file filtering** — Lua scripts, terminal configs, and VS Code extensions are excluded with logged warnings

Relevant functions: `theme_came_from_a_repo`, `stage_installed_theme`, and `report_ignored_theme_files` at **lines 71-78**.

## Palette Generation from Alacritty Configs

If [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is missing but [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) exists, the helper `omarchy-theme-colors-from-alacritty` generates the palette automatically.

```bash

# Auto-generated when needed

colors.toml ← alacritty.toml

```

See **lines 78-82** of `omarchy-theme-set`.

## Template Rendering with `omarchy-theme-set-templates`

The `bin/omarchy-theme-set-templates` script performs dynamic configuration generation:

1. Reads [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and builds a substitution map
2. Expands every `*.tpl` file under `default/themed/`
3. Processes user-provided templates if present
4. **Never overwrites** existing hand-written files

Output files include [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua), and other themed configurations.

Implementation at **lines 70-99** — note the guard condition "Only generate dynamic templates for themes with a colors.toml definition."

## Background Handling Pipeline

Background management runs in parallel with template rendering:

| Step | Function | Purpose |
|------|----------|---------|
| Snapshot | `snapshot_current_background` | Captures current wallpaper state |
| Selection | `choose_theme_background` | Picks next background image |
| Symlink | `set_theme_background` | Links to `~/.local/state/omarchy/current/background` |
| Transition | IPC notification | Requests smooth visual transition |

Implementation spans **lines 51-79**.

## Atomic Theme Swap

The staged `next-theme` directory **atomically replaces** the active theme:

```bash

# Atomic operation

next-theme/ → theme/

```

The active theme name persists to `theme.name` at **lines 91-96**.

## Live Shell Notification via IPC

The running shell receives instant palette updates through base64-encoded IPC:

```bash
omarchy-shell  # receives colors.toml + shell.toml

```

This **immediate update** at **lines 98-102** ensures the terminal reflects new colors before dependent applications restart.

## Parallel Post-Theme Command Execution

A predefined `post_theme_commands` array at **lines 18-33** restarts or retints dependent applications:

- Terminal emulator
- Hyprland compositor
- btop system monitor
- VS Code editor

Commands launch via `run_parallel` for minimal latency.

## Finalization: Hooks and Cache Warm-up

The activation concludes with:

1. **Hook execution**: `omarchy-hook theme-set` at line 38
2. **Selector cache preloading**: Theme switcher caches at lines 40-42
3. **Background daemon startup**: Cache warming at lines 44-46

## Theme Activation Examples

```bash

# Built-in theme activation

omarchy theme set "Tokyo Night"

# User-created theme with hand-written overrides

omarchy theme set my-custom-theme

# Git-installed theme (filtered during activation)

omarchy theme install https://github.com/example/omarchy-theme.git
omarchy theme set example-theme

```

## Key Source Files in the Activation Flow

| File | Repository Path | Role |
|------|-----------------|------|
| Main activation script | `bin/omarchy-theme-set` | Orchestrates the 11-step pipeline |
| Template engine | `bin/omarchy-theme-set-templates` | Renders `.tpl` files from palette |
| Color parser | `bin/omarchy-theme-color` | Provides key-value maps for templates |
| Documentation | [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) | "Theme activation flow" reference section |
| Official themes | `themes/<name>/` | Source of first-party themes |
| User themes | `~/.config/omarchy/themes/<name>/` | Overlay directory |
| Runtime state | `~/.local/state/omarchy/current/` | Active theme and background symlinks |

## Summary

- **Omarchy theme activation** uses atomic staging in `next-theme/` to prevent broken intermediate states
- The **11-step pipeline** handles validation, assembly, template rendering, background management, IPC notification, and parallel application restarts
- **File filtering** protects against malicious content in Git-installed themes
- **Template rendering** is conditional on [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) presence and preserves user customizations
- **Live IPC updates** ensure immediate visual feedback while background processes complete the transition

## Frequently Asked Questions

### What happens if a theme lacks a colors.toml file?

The activation flow checks at line 78 and attempts palette generation from [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) using `omarchy-theme-colors-from-alacritty`. If neither exists, template rendering is skipped entirely — the "Only generate dynamic templates for themes with a colors.toml definition" guard at line 70 prevents errors.

### How does Omarchy prevent theme corruption during concurrent changes?

The `omarchy-theme-set` script acquires a filesystem lock at startup. This serializes all theme changes, ensuring only one activation proceeds at a time regardless of how many `omarchy theme set` commands are issued.

### Why are some files filtered from Git-installed themes?

Security and compatibility. The `report_ignored_theme_files` function at lines 71-78 explicitly removes Lua scripts, terminal configurations, and VS Code extensions. This prevents third-party themes from executing arbitrary code or overriding critical system settings.

### Can I override specific theme files without forking the entire theme?

Yes. Place files in `~/.config/omarchy/themes/<name>/` — these overlay on top of the base theme during activation. Hand-written files in the staging directory are never overwritten by the template engine, preserving your customizations across theme updates.