` in the filename to replace only a specific section of a generated file: ```bash # Replace only the [lock] section of shell.toml cat > ~/.config/omarchy/themes/my-theme/shell.lock.toml <<'EOF' [lock] text = "#ffffff" placeholder = "#aaaaaa" border = "#ff6e6b" EOF ``` This pattern works for any TOML-based configuration that Omarchy generates. ## Custom Templates for Unsupported Apps To theme applications not covered by Omarchy's built-in templates, add user-wide custom templates: 1. Create the directory: `mkdir -p ~/.config/omarchy/themed/` 2. Write a template file with `.tpl` extension, e.g., `myapp.conf.tpl` 3. Reference palette keys with `{{ variable_name }}` syntax ```bash # Example: ~/.config/omarchy/themed/alacritty.yml.tpl cat > ~/.config/omarchy/themed/alacritty.yml.tpl <<'EOF' colors: primary: background: '{{ background }}' foreground: '{{ foreground }}' normal: black: '{{ background }}' red: '{{ red }}' green: '{{ green }}' blue: '{{ blue }}' EOF ``` These templates render alongside built-ins when you apply your theme. ## Security Note on Code Execution Omarchy applies different trust levels based on theme origin: - **Manually created themes** (in `~/.config/omarchy/themes/`): All files preserved, including executable code - **Installed/git-cloned themes**: Files that could execute—`.lua` scripts, terminal configs, [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json)—are stripped for security Non-executable files like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), `icons.theme`, and `backgrounds/` directories copy verbatim regardless of origin. ## Previewing and Applying Your Theme Apply your theme and preview the results: ```bash # Apply the theme omarchy-theme-set my-theme # Preview the color ramp and verify placeholder resolution omarchy dev theme-preview my-theme ``` The `theme-preview` command renders the theme in a staging directory without installing it, showing you exactly how palette values expand across all generated files. ## Sharing Your Theme To distribute your theme, publish it as a Git repository following the naming convention `omarchy--theme`: ```bash cd ~/.config/omarchy/themes/my-theme git init git add . git commit -m "Initial My Theme release" git remote add origin https://github.com/yourname/omarchy-my-theme.git git push -u origin main ``` Users install it with: ```bash omarchy theme install https://github.com/yourname/omarchy-my-theme.git omarchy-theme-set my-theme ``` ## Complete Theme File Structure A fully-featured custom Omarchy theme may include: | File | Purpose | |------|---------| | [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) | Semantic palette definition (required) | | [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) | Full shell config override | | `shell.

.toml` | Partial shell config override | | `icons.theme` | Icon theme selection for file managers | | `backgrounds/` | Wallpaper images | | `unlock.png` | Custom unlock screen image (transparent PNG recommended) | | `*.toml` (other) | Overrides for other generated configs | ## Summary - **Create** a custom Omarchy theme in `~/.config/omarchy/themes//` by copying an existing theme - **Define** your palette in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) with semantic color keys and optional `mode = "light"` or `"dark"` - **Override** specific configurations with full files (e.g., [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml)) or partial sections (e.g., [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml)) - **Extend** support to new applications by adding custom `.tpl` templates to `~/.config/omarchy/themed/` - **Apply** with `omarchy-theme-set ` and preview with `omarchy dev theme-preview ` - **Share** by pushing to a Git repository and instructing users to run `omarchy theme install ` ## Frequently Asked Questions ### What is the minimum required structure for a workable Omarchy theme? A valid Omarchy theme requires only [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) in the theme directory. All other files are generated from templates using the palette values defined there. You can add override files or custom templates as needed, but the palette alone is sufficient for a functional theme. ### Can I override just one color value without replacing an entire file? Yes. Create a partial override file using the [`filename.section.toml`](https://github.com/omacom/omarchy/blob/main/filename.section.toml) naming pattern. For example, [`shell.prompt.toml`](https://github.com/omacom/omarchy/blob/main/shell.prompt.toml) replaces only the `[prompt]` section of the generated shell configuration while preserving all other sections. ### Why are some files missing when I install a theme from Git? Omarchy's `theme install` command strips potentially executable files—`.lua` scripts, terminal configurations, [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json), and similar—as a security measure. This applies only to git-cloned themes. Files you create manually in `~/.config/omarchy/themes/` are preserved unconditionally. ### Do light mode themes require different templates? No. Templates handle light versus dark mode automatically. Set `mode = "light"` in your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and use the same template files. Applications that respect the mode setting will adapt accordingly; those that don't will use your literal palette values. ### How do I add support for an application Omarchy doesn't theme yet? Create a custom template in `~/.config/omarchy/themed/` with a `.tpl` extension and the exact filename you want generated. Reference palette keys with `{{ variable_name }}` syntax. Run `omarchy-theme-set` to render it alongside built-in templates.