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

> Learn how the omarchy-theme-set command activates a theme by locking files, rendering templates, running update scripts, and firing a theme-set hook for full desktop synchronization.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# Apply the "Tokyo Night" theme across all components

omarchy-theme-set "Tokyo Night"

```

```bash

# Activate a theme while skipping background changes

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

```

```bash

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