How the Omarchy Branding System Works with Plymouth, About, and Screensaver

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:

# 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 via callbacks in default/plymouth/omarchy.script that call Plymouth.SetMessage and Plymouth.ShowMessage.
• The idle screensaver displays 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 <path> 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 file itself.

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