What Is the Purpose of shell.toml in Omarchy's Configuration?

shell.toml is the central configuration file that defines the visual language of the Omarchy shell, declaratively specifying surface-role colors, control states, spacing tokens, and typography that QML components consume through the Color and Style singletons.

The shell.toml file sits at the heart of Omarchy's theming architecture, bridging static configuration with dynamic runtime behavior. According to the basecamp/omarchy source code, this TOML file provides a hot-reloadable source of truth for all UI styling without requiring shell restarts.

Core Responsibilities and Structure

Visual Surface Roles and Control States

At its foundation, shell.toml organizes colors into semantic surface roles that QML components reference through the Color singleton defined in shell/Commons/Color.qml. The configuration groups related colors into tables such as [bar], [menu], and [tooltip], each defining background and foreground values for specific UI regions.

Beyond static colors, the file declares control-state definitions including hover, active, and disabled variants. These states allow widgets to react to user interaction while maintaining visual consistency across the shell.

Layout Metrics and Typography Definitions

The configuration also drives structural calculations through spacing and sizing tokens. Values for margins, paddings, and bar height live directly in shell.toml, enabling theme authors to adjust density without modifying QML source.

Typography receives similar treatment through the [font] table, which specifies base-size, family, and weight. The Style singleton in shell/Commons/Style.qml propagates these values to every widget, ensuring consistent text rendering across panels, menus, and tooltips.

Theme Generation and Override Architecture

Template-Based File Generation

When applying a theme, Omarchy generates shell.toml from the template located at default/themed/shell.toml.tpl. This template serves as the fallback source, providing default values for all visual tokens when a theme does not explicitly override them.

Theme-Level and User-Level Overrides

Themes can customize the shell appearance through two distinct mechanisms:

1. Theme-provided override: Shipping a file at themes/<name>/shell.toml within the theme directory replaces the generated defaults entirely.
2. User-level override: Creating ~/.config/omarchy/shell.toml on the local machine applies machine-specific customizations that persist across theme changes.

If a theme omits the shell.toml file, Omarchy automatically falls back to the template defaults, ensuring the shell remains functional regardless of theme completeness.

Runtime Loading and Configuration Merging

Configuration Precedence Model

At runtime, the shell loads two distinct TOML dictionaries that the Color singleton merges according to a strict precedence hierarchy:

• Theme-provided: Located at $OMARCHY_PATH/themes/<theme>/shell.toml, this file contains the theme author's intended styling.
• User-provided: Found at ~/.config/omarchy/shell.toml, this file contains local machine overrides.

The merging algorithm gives explicit precedence to the user file, allowing local customizations to override theme defaults without modifying the theme package itself.

Live Reloading Implementation

The architecture supports live reloading of colors, spacing, and font settings without restarting the shell. When users execute the omarchy-theme-set <theme-name> command, the CLI base-64-encodes the theme's shell.toml and transmits it to the running shell via the applyTheme <colorsB64> <shellB64> function. The shell receives this payload, re-merges the configuration dictionaries, and immediately updates all bound QML properties.

Practical Configuration Examples

Customizing User Settings

Edit ~/.config/omarchy/shell.toml to modify bar backgrounds and base font sizes:

[bar]
background = "#1e1e2e"

[font]
base-size = 13

Applying Themes Programmatically

Use the bundled CLI tool to switch themes and push configuration to the running shell:

omarchy-theme-set <theme-name>

This command internally base-64-encodes the theme's shell.toml and invokes the shell's theme application interface.

Accessing Values in QML Components

QML files import the Commons namespace to access merged configuration values:

import "Commons" as Commons

Text {
    text: "Info"
    color: Commons.Color.tooltip.foreground
    font.pixelSize: Commons.Style.font.baseSize
}

The Commons.Color object exposes surface-role colors, while Commons.Style provides typography and spacing metrics sourced directly from the merged shell.toml dictionaries.

Summary

• shell.toml is the declarative configuration file controlling Omarchy's entire visual language, located thematically at default/themed/shell.toml.tpl and overridden at runtime.
• The file defines surface-role colors, control states, spacing tokens, and typography that QML components consume through singletons.
• Theme authors override defaults by placing shell.toml in their theme directory, while users customize via ~/.config/omarchy/shell.toml with automatic precedence.
• The Color singleton in shell/Commons/Color.qml merges theme and user configurations, enabling hot reloading without shell restarts.
• The omarchy-theme-set CLI command encodes and transmits configuration changes via the applyTheme function interface.

Frequently Asked Questions

What file format does Omarchy use for shell configuration files?

Omarchy uses TOML (Tom's Obvious, Minimal Language) for its shell configuration. The shell.toml file uses section headers like [bar] and [font] to organize related configuration keys, making it human-readable and easy to edit for both theme authors and end users.

Where should I place my custom shell.toml overrides?

Place user-specific overrides in ~/.config/omarchy/shell.toml. This location takes precedence over theme-provided configurations located at $OMARCHY_PATH/themes/<theme>/shell.toml. The shell automatically detects and merges this file at startup and during theme switches.

How does Omarchy apply theme changes without restarting?

Omarchy implements a live reloading mechanism through base-64-encoded configuration transmission. When you run omarchy-theme-set, the CLI encodes the theme's shell.toml and calls applyTheme <colorsB64> <shellB64>, which the running shell receives and applies immediately to all QML singletons.

Can I modify just the font size without creating a full theme?

Yes. Create or edit ~/.config/omarchy/shell.toml and add a [font] section with your desired base-size value. The bin/omarchy-display-text-size utility demonstrates how the shell reads this specific key to adjust text rendering across all widgets without requiring a custom theme package.

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