How to Migrate an Omarchy Theme from alacritty.toml to colors.toml

Migrating an Omarchy theme from alacritty.toml to colors.toml requires extracting the color palette from the legacy terminal configuration, creating a standardized colors.toml file in the theme directory, and removing the old alacritty.toml to let Omarchy generate a fresh terminal config from its template.

Omarchy themes have shifted from shipping terminal-specific configurations to using a centralized palette system. When migrating an Omarchy theme from alacritty.toml to colors.toml, you convert legacy color definitions into the modern schema used by the omacom/omarchy repository to generate consistent theming across all applications. This process ensures your theme follows the current architecture where colors.toml serves as the single source of truth.

How Omarchy Handles Legacy Themes Automatically

When a theme lacks colors.toml, Omarchy detects this during theme staging in bin/omarchy-theme-set (lines 313-314). The system automatically invokes the helper omarchy-theme-colors-from-alacritty to parse the palette from alacritty.toml and write a temporary colors.toml into a scratch directory.

However, the original alacritty.toml is never copied into the active theme (lines 186-202 of bin/omarchy-theme-set). This means the legacy configuration is discarded during staging, and only the extracted palette survives. While this automatic conversion ensures themes remain functional, theme authors should perform a manual migration to clean up source repositories and ensure long-term maintainability.

Step-by-Step Migration Process

Step 1: Extract the Palette from alacritty.toml

Identify all color definitions in your existing alacritty.toml. The conversion routine reads standard palette keys including foreground, background, accent, selection, muted, red, green, yellow, blue, magenta, and cyan.

Copy these hex values into a temporary reference. For example, note values like foreground = "#a9b1d6" and accent = "#7aa2f7" for transplantation into the new structure.

Step 2: Create the New colors.toml File

Create colors.toml in your theme directory (themes/<name>/colors.toml) using the standardized schema documented in docs/theming.md (lines 70-93). The file must declare the mode and define all palette variables.

mode = "dark"

accent = "#7aa2f7"
selection = "#292e42"
muted = "#414868"

background = "#1a1b26"
dark_background = "#13141c"
darker_background = "#0e0e14"
lighter_background = "#24283b"

foreground = "#a9b1d6"
dark_foreground = "#565f89"
light_foreground = "#b4bee6"
bright_foreground = "#c0caf5"

red = "#f7768e"
green = "#9ece6a"
yellow = "#e0af68"
blue = "#7aa2f7"
magenta = "#bb9af7"
cyan = "#7dcfff"

This hierarchical structure replaces the flat Alacritty configuration and enables Omarchy to generate configurations for multiple applications from a single source.

Step 3: Remove the Legacy alacritty.toml

Delete the old alacritty.toml from your theme directory. Omarchy will automatically generate a fresh terminal configuration using the template default/themed/alacritty.toml.tpl rendered with values from your new colors.toml.

The generated file is written to ~/.local/state/omarchy/current/theme/alacritty.toml when you apply the theme. Keeping the legacy file in the theme directory prevents Omarchy from using the standardized generation pipeline and may cause configuration drift.

Step 4: Verify the Migration with Testing

Activate your migrated theme and run the test suites to ensure no legacy configuration leaks into the staged environment:

omarchy theme set my-theme
./test/cli
./test/shell

The shell tests in test/shell.d/theme-staging-test.sh (lines 134-160) include assertions like assert_no_marker alacritty.toml to verify that legacy terminal configs are correctly excluded from the active theme at ~/.local/state/omarchy/current/theme/.

Understanding the Theme Generation Flow

When you apply a theme containing colors.toml, Omarchy renders default/themed/alacritty.toml.tpl with values from your palette. This ensures the terminal configuration stays synchronized with the central color definitions.

If you need a custom terminal configuration that differs from the generated defaults, you may keep a manually edited alacritty.toml in the theme directory. However, this breaks the single-source-of-truth model and is not recommended for standard themes, as it prevents automatic updates when the core template improves.

Summary

• Modern Omarchy themes use colors.toml as the central palette definition, replacing legacy alacritty.toml files that were parsed at install-time.
• Automatic conversion occurs during staging via bin/omarchy-theme-colors-from-alacritty when colors.toml is missing, but manual migration is required for clean theme maintenance.
• Key files involved include bin/omarchy-theme-set for staging logic, docs/theming.md for the schema reference, and default/themed/alacritty.toml.tpl for terminal generation.
• Testing with ./test/cli and ./test/shell ensures the migration completes without leaving stray configuration files in the active theme.

Frequently Asked Questions

What happens if I keep both alacritty.toml and colors.toml in my theme?

If both files exist, Omarchy will stage the colors.toml as the palette source but will not overwrite a manually provided alacritty.toml. However, this creates maintenance overhead since the terminal configuration won't update automatically when you modify the palette. The recommended approach is to remove alacritty.toml and let Omarchy generate it from the template.

Does Omarchy support light mode in colors.toml?

Yes, the colors.toml schema supports a mode key that accepts "dark" or "light" values. When creating your migration file, set mode = "light" for light themes. Omarchy uses this value to adjust generation logic where applications support distinct light and dark variants.

How do I verify that my legacy alacritty.toml isn't being staged?

Run the shell test suite with ./test/shell and examine the theme staging tests in test/shell.d/theme-staging-test.sh. These tests verify that legacy files like alacritty.toml are excluded from the staged theme directory. If the assert_no_marker alacritty.toml assertion passes, your migration is clean and the legacy file is not being copied to ~/.local/state/omarchy/current/theme/.

Can I customize the generated alacritty.toml template?

While you can edit default/themed/alacritty.toml.tpl to change how Omarchy generates terminal configurations for all themes, this affects the entire system. For theme-specific customizations, you would need to ship a custom alacritty.toml, though this prevents the theme from benefiting from future template updates in the Omarchy core.

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