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

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

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.

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

$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 is missing but alacritty.toml exists, the helper omarchy-theme-colors-from-alacritty generates the palette automatically.

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

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

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

# 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	"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 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 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.

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