How Omarchy Syncs Terminal Colors: Complete Architecture Guide

Omarchy syncs terminal colors by reading a centralized colors.toml palette, converting it to terminal-specific syntax via omarchy-theme-color, and writing the result to each terminal's config file—triggered automatically whenever omarchy-theme-set changes themes.

Omarchy is an open-source desktop environment that unifies application theming through a single source of truth. Understanding how terminal color synchronization works reveals the design patterns that keep Alacritty, Foot, Kitty, and other terminals visually consistent with your active theme. This guide examines the exact scripts, file paths, and data flow that make this possible.

---

The Central Color Definition: colors.toml

Every Omarchy theme stores its complete color palette in a TOML file located within the theme directory.

The canonical location for the default theme is:

themes/default/colors.toml

This file contains:

• 16 standard terminal colors (color0 through color15)
• Bright variant mappings
• Foreground, background, and cursor colors

By centralizing color data in a structured format, Omarchy eliminates the need to manually edit multiple terminal configuration files. The colors.toml serves as the single source of truth that downstream scripts consume.

---

The Conversion Engine: omarchy-theme-color

The script bin/omarchy-theme-color performs the heavy lifting of palette-to-config translation.

What It Does

1. Parses the active theme's colors.toml
2. Maps each color value to the appropriate configuration syntax for supported terminals
3. Writes the resulting configuration blocks to user config directories

Terminal-Specific Output Formats

Terminal	Target File	Syntax Style
Alacritty	~/.config/alacritty/alacritty.yml	YAML colors: block
Foot	~/.config/foot/foot.ini	INI [colors] section
Kitty	~/.config/kitty/kitty.conf	Line-based colorN #hex declarations

The script preserves existing non-color settings in these files. It achieves this by:

• Reading the current config
• Detecting and replacing only the color-related sections
• Performing an atomic write (temporary file first, then move)

This ensures users don't lose custom keybindings, font settings, or other terminal-specific preferences.

---

The Trigger Mechanism: omarchy-theme-set

Theme changes propagate to terminals through bin/omarchy-theme-set, the entry point for all theme switches.

Execution Flow

When you run:

omarchy-theme-set dracula

The script performs this sequence:

1. Copies theme files to ~/.config/omarchy
2. Applies template transformations
3. Calls omarchy-theme-color to synchronize terminal colors
4. Refreshes any running applications that support live theme reloading

This integration means terminal colors stay synchronized without manual intervention. The sync happens automatically as a side effect of every theme change.

---

Reverse Import: omarchy-theme-colors-from-alacritty

Omarchy supports round-trip color management through bin/omarchy-theme-colors-from-alacritty.

Use Case

You've manually crafted the perfect color scheme in Alacritty and want to convert it to a reusable Omarchy theme.

How It Works

omarchy-theme-colors-from-alacritty ~/.config/alacritty/alacritty.yml

The script:

• Parses the colors: section from the YAML file
• Maps Alacritty's color keys to Omarchy's colors.toml structure
• Writes the result to ~/.config/omarchy/themes/custom/colors.toml

This enables bi-directional color workflow: you can start with any terminal's configuration and elevate it to a system-wide Omarchy theme.

---

File Architecture and Source Locations

Understanding the repository structure clarifies how these components interconnect:

Path	Purpose
bin/omarchy-theme-set	Main theme-switching command that orchestrates all sync operations
bin/omarchy-theme-color	Color conversion script for terminal emulators
bin/omarchy-theme-colors-from-alacritty	Import utility for extracting colors from existing Alacritty configs
themes/*/colors.toml	Canonical color palettes (one per theme)
default/theme/*.tpl	Template files that inject colors into non-terminal applications

All scripts reside in the bin/ directory and operate on files within ~/.config/omarchy and standard XDG config paths.

---

Practical Code Examples

Switch themes with automatic terminal sync

omarchy-theme-set solarized-dark

This single command updates GTK, Qt, shell prompts, and all supported terminals.

Force a manual color resync

omarchy-theme-color

Use this when you've edited colors.toml directly and want to propagate changes without switching themes.

Import from existing Alacritty configuration

omarchy-theme-colors-from-alacritty ~/.config/alacritty/my-theme.yml

Creates a new Omarchy theme named custom containing the extracted palette.

Check which theme is currently active

cat ~/.config/omarchy/active-theme
omarchy-theme-color --dry-run  # Preview what would be written

---

Supported Terminal Extensibility

The omarchy-theme-color script uses a modular backend system. Each terminal type has a dedicated conversion function:

• Alacritty: YAML manipulation with yaml or line-based regex fallback
• Foot: INI section management
• Kitty: Line-oriented configuration with color deduplication

Adding support for new terminals requires implementing:

1. A parser for the terminal's config format
2. A templating function that maps Omarchy's 16-color palette to the terminal's expected keys
3. An atomic write routine that preserves unrelated settings

The script's structure encourages this extensibility through isolated handler functions.

---

Summary

• Single source of truth: colors.toml in each theme directory defines the complete palette
• Automatic propagation: omarchy-theme-set triggers omarchy-theme-color on every theme change
• Multiple terminal support: Alacritty, Foot, and Kitty receive native config updates with existing settings preserved
• Round-trip capable: omarchy-theme-colors-from-alacritty imports existing terminal themes into Omarchy's ecosystem
• Atomic writes: All config modifications use temporary files to prevent corruption

---

Frequently Asked Questions

How do I add a new terminal emulator to Omarchy's sync system?

Extend bin/omarchy-theme-color with a new handler function that reads your terminal's config format and maps the 16 colors from colors.toml to its expected structure. Follow the existing Alacritty or Kitty implementations as templates, ensuring you preserve non-color settings through atomic file operations.

Why didn't my terminal colors change after running omarchy-theme-set?

Verify your terminal is in the supported list (Alacritty, Foot, Kitty). Check that ~/.config/omarchy-theme-color executed without errors. Some terminals require a restart to reload configuration—live reloading depends on the terminal's file-watching capabilities, not Omarchy's scripts.

Can I use omarchy-theme-color without changing my active theme?

Yes. Running omarchy-theme-color without arguments re-applies the current theme's colors to all supported terminals. This is useful after manually editing colors.toml or when terminal config files have been corrupted or deleted.

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