# How the Omarchy Branding System Works with Plymouth, About, and Screensaver > Learn how the Omarchy branding system creates custom ASCII art for Plymouth, About dialogs, and screensavers using simple text files and helper commands. Customize your system's visual identity. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-10 --- **Omarchy uses two plain-text files in `~/.config/omarchy/branding/` to render custom ASCII art during the Plymouth boot About dialog and the idle screensaver, managed through helper commands that convert images or edit text directly.** The omacom/omarchy repository ships a self-contained branding subsystem that bridges early-boot visual elements with session idle screens. By storing user-editable ASCII art in plain text files, the system persists customizations across updates while integrating with Plymouth's C-API and terminal-based screensaver tools. ## How Plymouth Consumes the About Branding During early boot, after the initial splash screen, Plymouth displays an informational About dialog that renders the contents of `~/.config/omarchy/branding/about.txt`. The default Plymouth theme, defined in `default/plymouth/omarchy.plymouth` and scripted in `default/plymouth/omarchy.script`, reads this file through specific callbacks. ### The omarchy.script Callback Architecture The Plymouth theme script registers display callbacks such as `display_message_callback` and `display_normal_callback` that interface with the Plymouth C-API. When triggered, these callbacks invoke `Plymouth.SetMessage` and `Plymouth.ShowMessage` to render the ASCII art stored in the user's branding file. This mechanism allows the About dialog to update dynamically without rebuilding the initramfs. ### Reading about.txt During Boot The script directly sources `~/.config/omarchy/branding/about.txt` during the boot sequence. Because this path resides in the user's home directory rather than system directories, modifications take effect immediately on the next boot without requiring administrative privileges or theme recompilation. ## Configuring Screensaver Branding When the session enters an idle state, the `omarchy-screensaver` command activates and displays fullscreen ASCII art from `~/.config/omarchy/branding/screensaver.txt`. Unlike the Plymouth integration, which operates during the boot process, the screensaver functions entirely within the user session. ### The omarchy-screensaver Command Located at `bin/omarchy-screensaver`, this executable pipes the screensaver branding file through `ttfx`, a lightweight terminal graphics viewer. The command runs automatically when idle time thresholds are met, or manually via the Style menu entries defined in `default/omarchy/omarchy-menu.jsonc`. ### File Location and Rendering Pipeline The screensaver branding file follows the same location pattern as the About branding. When `omarchy-screensaver` executes, it reads `~/.config/omarchy/branding/screensaver.txt` and passes the content to `ttfx` for fullscreen terminal rendering. This approach maintains consistency with the Plymouth About screen while using session-appropriate display tools. ## CLI Tools for Branding Management Omarchy provides two primary helper commands that abstract the file manipulation and format conversion required for both branding elements. These tools ensure the ASCII art meets the display requirements of their respective targets. ### omarchy-branding-about Commands The `bin/omarchy-branding-about` script accepts three subcommands: - **`image`** – Opens a file picker dialog, transcodes PNG or SVG files to ASCII using `omarchy-transcode-ascii`, and writes the output to `~/.config/omarchy/branding/about.txt`. - **`text`** – Opens the existing ASCII file in the user's default editor via `omarchy-launch-editor`. - **`reset`** – Restores the default Omarchy icon by copying `$OMARCHY_PATH/icon.txt` into the user's branding file. ### omarchy-branding-screensaver Commands Symmetrically, `bin/omarchy-branding-screensaver` implements identical actions for the screensaver file: ```bash # Convert an image for the screensaver (100 character width) omarchy-branding-screensaver image ~/Pictures/clock.png # Edit screensaver text manually omarchy-branding-screensaver text # Restore default screensaver art omarchy-branding-screensaver reset ``` ### Image Transcoding to ASCII Both helpers rely on `bin/omarchy-transcode-ascii` to convert raster and vector images into terminal-compatible ASCII art. This utility handles the character-width constraints and color mapping required for faithful representation in both Plymouth's limited display environment and terminal emulators. ## Menu Integration and User Workflow The Omarchy graphical menu exposes these branding controls through standardized entries, ensuring CLI and GUI workflows remain synchronized. ### Style Menu Entries The menu configuration in `default/omarchy/omarchy-menu.jsonc` defines entries under *Style → About* and *Style → Screensaver*. Selecting these entries invokes the corresponding helper commands (`omarchy-branding-about` or `omarchy-branding-screensaver`) with the appropriate action flags. This design keeps the UI logic thin while leveraging the same validation and conversion routines used on the command line. ### Animation Effects The About screen supports a visual sheen effect implemented in `bin/omarchy-branding-about-animation`. This module is sourced by `bin/omarchy-launch-about` and runs when the Plymouth dialog appears, adding a polished transition to the static ASCII art without modifying the underlying branding file. ## Summary - Omarchy stores branding files in `~/.config/omarchy/branding/` as plain text ASCII art, ensuring configurations survive system updates. - The Plymouth About screen renders [`about.txt`](https://github.com/omacom/omarchy/blob/main/about.txt) via callbacks in `default/plymouth/omarchy.script` that call `Plymouth.SetMessage` and `Plymouth.ShowMessage`. - The idle screensaver displays [`screensaver.txt`](https://github.com/omacom/omarchy/blob/main/screensaver.txt) using `bin/omarchy-screensaver` piped through `ttfx` for fullscreen terminal rendering. - Helper commands `omarchy-branding-about` and `omarchy-branding-screensaver` provide `image`, `text`, and `reset` actions for both elements. - The Style menu entries in `default/omarchy/omarchy-menu.jsonc` call these same CLI tools, maintaining consistency between interface methods. ## Frequently Asked Questions ### Where does Omarchy store custom branding files? Omarchy places user-editable branding files at `~/.config/omarchy/branding/about.txt` and `~/.config/omarchy/branding/screensaver.txt`. Because these paths reside in the user's home directory under XDG-compliant locations, they persist through system updates and migrations without requiring backup scripts. ### How do I convert an image to ASCII for the About screen? Run `omarchy-branding-about image ` to open a file picker, or specify the path directly. The command invokes `omarchy-transcode-ascii` to convert PNG or SVG files into terminal-compatible ASCII art and writes the result to `~/.config/omarchy/branding/about.txt`, making it available for the next boot's Plymouth About dialog. ### What happens to my branding during an Omarchy update? Branding files remain untouched during updates because they live in `~/.config/omarchy/branding/` rather than system directories. The `bin/omarchy-reinstall-configs` script creates these files only on fresh installs when they are missing, ensuring existing customizations are preserved while still allowing restoration to defaults via the `reset` command. ### Can I animate the Plymouth About screen? Yes, the About screen includes a sheen animation effect provided by `bin/omarchy-branding-about-animation`. This module is loaded by `bin/omarchy-launch-about` and executes when the Plymouth dialog appears, adding motion to the static ASCII art without requiring modifications to the [`about.txt`](https://github.com/omacom/omarchy/blob/main/about.txt) file itself.