How the omarchy-theme-set Command Activates a Theme Across Omarchy

The omarchy-theme-set command activates a theme by acquiring a file lock, rendering template files into concrete configuration, dispatching subsystem-specific update scripts, and firing a theme-set hook to synchronize your entire desktop environment.

The omarchy-theme-set command serves as the central orchestrator for theme activation in the Basecamp Omarchy dotfiles repository. When you invoke it with a theme name, it executes a deterministic pipeline that atomically updates your terminal, window manager, editors, and browsers. Understanding this activation flow is essential for customizing themes or debugging configuration drift across your Omarchy installation.

The Theme Activation Pipeline

The activation logic resides in bin/omarchy-theme-set and follows a strict four-phase pipeline to ensure consistency across all Omarchy components.

Step 1: Acquiring the Theme Lock

To prevent race conditions during concurrent operations, the script creates a lock file at ${XDG_RUNTIME_DIR:-/tmp}/omarchy-theme-set.lock before performing any modifications (see line 16 of bin/omarchy-theme-set). This guarantees that only one theme activation runs at a time, protecting the integrity of your configuration files from simultaneous writes.

Step 2: Rendering Template Files

Next, the script invokes omarchy-theme-set-templates to process all *.tpl files located in default/themed/* (line 156). This step transforms abstract theme definitions into concrete configuration files for tools like Alacritty, Starship, and tmux, embedding the selected theme's color values into the generated output before any live application occurs.

Step 3: Dispatching Subsystem Updates

After templates are rendered, omarchy-theme-set calls a series of specialized scripts defined in its post_theme_commands block (lines 196-204) to push the theme into each subsystem:

• omarchy-theme-set-foot – Updates the foot terminal configuration with new color values.
• omarchy-theme-set-tmux – Writes tmux color settings to the appropriate configuration path.
• omarchy-theme-set-gnome – Applies Gnome and dconf theme values through gsettings.
• omarchy-theme-set-pi – Handles Raspberry Pi-specific theme files and displays.
• omarchy-theme-set-claude – Configures Claude AI theme files for consistent AI assistant theming.
• omarchy-theme-set-browser – Synchronizes the browser color scheme via userChrome or extension APIs.
• omarchy-theme-set-vscode – Updates Visual Studio Code settings.json with the new color theme.
• omarchy-theme-set-obsidian – Patches Obsidian vault theme files.
• omarchy-theme-set-keyboard – Adjusts keyboard-layout-specific themes for hardware LED or on-screen display.

Each subcommand knows the exact file paths or APIs for its target application and writes the appropriate color values directly to the relevant configuration stores.

Step 4: Firing the theme-set Hook

Once all components are updated, the script executes omarchy-hook-run theme-set to trigger any user-defined extensions. According to docs/theming.md (line 38), this hook mechanism allows custom scripts in the hook directory to react to theme changes and perform additional post-processing, such as regenerating caches or notifying other daemons.

Headless and Conditional Activation Modes

The command supports environment variables that modify its behavior for automation and specific use cases.

When OMARCHY_THEME_HEADLESS=1 is set, the script skips the live post-theme actions and performs only the template rendering phase. This mode is used by omarchy-theme-refresh (lines 8-9) during background updates to avoid disrupting the active session with flashing windows or reloads.

You can also skip specific components using variables like OMARCHY_THEME_SKIP_BACKGROUND=1 to prevent background-related updates while still applying terminal and editor themes.

Practical Usage Examples

Here are common patterns for invoking omarchy-theme-set from your terminal or scripts:

# Apply the "Tokyo Night" theme across all components

omarchy-theme-set "Tokyo Night"

# Activate a theme while skipping background changes

OMARCHY_THEME_SKIP_BACKGROUND=1 omarchy-theme-set "$(cat $HOME/.config/omarchy/theme_name)"

# Run in headless mode for automated refreshes (no live UI updates)

OMARCHY_THEME_HEADLESS=1 omarchy-theme-set "Solarized Dark"

Summary

• omarchy-theme-set acts as the central dispatcher for theme activation in the Omarchy environment, located at bin/omarchy-theme-set.
• The locking mechanism prevents concurrent theme changes from corrupting configuration files by using a runtime lock file.
• Template rendering converts *.tpl files in default/themed/* into concrete config files for terminals and development tools.
• Subsystem scripts (foot, tmux, gnome, vscode, obsidian, etc.) handle the specific implementation details for each target application.
• The theme-set hook provides an extension point for custom post-activation scripts registered via omarchy-hook-run.
• Headless mode supports automated updates via OMARCHY_THEME_HEADLESS=1 without triggering live UI refreshes.

Frequently Asked Questions

What happens if I run omarchy-theme-set while another theme change is in progress?

The script creates a lock file at ${XDG_RUNTIME_DIR:-/tmp}/omarchy-theme-set.lock at line 16 to prevent concurrent executions. If a lock exists, subsequent invocations will block or fail safely, ensuring your configuration files remain consistent and uncorrupted during parallel operations.

How do I prevent omarchy-theme-set from changing my desktop background?

Set the OMARCHY_THEME_SKIP_BACKGROUND=1 environment variable before running the command. This allows you to apply terminal and editor themes while preserving your current wallpaper or background configuration, effectively skipping the background subsystem update in the post-theme commands.

Can I automate theme changes without disturbing my active session?

Yes. Run omarchy-theme-set with OMARCHY_THEME_HEADLESS=1 to render templates and update configuration files without triggering the live post-theme commands that flash windows or reload interfaces. This is the mechanism used by omarchy-theme-refresh to perform background updates while you continue working.

Where are the theme-specific templates stored?

Theme templates are stored as *.tpl files in the default/themed/ directory. The omarchy-theme-set-templates helper, invoked by the main script at line 156, renders these templates into actual configuration files during the activation pipeline, substituting color values specific to your selected theme.

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