# How Omarchy Syncs Terminal Colors: Complete Architecture Guide

> Discover how Omarchy syncs terminal colors. Learn the architecture, from centralizing palettes to generating theme files, and understand the automated process triggered by theme changes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: architecture
- Published: 2026-08-31

---

**Omarchy syncs terminal colors by reading a centralized [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-color) performs the heavy lifting of **palette-to-config translation**.

### What It Does

1. **Parses** the active theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set), the **entry point for all theme switches**.

### Execution Flow

When you run:

```bash
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`](https://github.com/omacom/omarchy/blob/quattro/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

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

```bash
omarchy-theme-set solarized-dark

```

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

### Force a manual color resync

```bash
omarchy-theme-color

```

Use this when you've edited [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) directly and want to propagate changes without switching themes.

### Import from existing Alacritty configuration

```bash
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

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) or when terminal config files have been corrupted or deleted.