Customizing Skins and Themes

Relevant source files

The following files were used as context for generating this wiki page:

• skills/autonomous-ai-agents/hermes-agent/references/themes.md
• hermes_cli/skin_engine.py
• ui-tui/src/theme.ts
• agent/learn_prompt.py
• skills/software-development/hermes-agent-skill-authoring/SKILL.md
• optional-skills/creative/auteur/templates/DESIGN.md

Hermes Agent uses a centralized skin engine to provide consistent visual identities across the Command Line Interface (CLI), Terminal User Interface (TUI), and Desktop Graphical User Interface (GUI). A skin is defined by a single YAML file that dictates color palettes and semantic UI elements for every surface.

The system relies on a "semantic theming" approach where specific keys color elements based on their role in the interface. When the active skin changes, the gateway broadcasts the update to all active surfaces, enabling live repainting without requiring application restarts.

Architecture and Data Flow

The skin_engine.py component resolves the active skin from user configuration and manages the loading of YAML theme files. Themes are stored in the .hermes/skins/ directory within the user's home or profile path.

The diagram shows how the skin engine merges configured skin files with default values and pushes the results to various interface surfaces.
Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:8-13, hermes_cli/skin_engine.py

Live Repainting Logic

The gateway maintains a skin watcher that monitors changes to the active skin configuration. When a user updates a theme value using the hermes skin set or hermes config set commands, the watcher triggers a broadcast. Every surface repaints within approximately one second of the tool finishing its execution.
Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:36-41

Semantic Mapping

Hermes themes use semantic keys rather than mapping to raw terminal colors. This ensures that a "secondary" text element looks appropriate regardless of the background color.

Key	Description	Fallback Behavior
background	Primary background color for TUI and GUI.	Terminal default
ui_accent	Primary accent color for headings, links, and symbols.	None
ui_tool	Color for tool-call markers and spinners.	ui_accent
ui_thinking	Color for agent reasoning/thinking blocks.	banner_dim
ui_primary	Heading and primary text color.	None
ui_text	Body and user message text.	None
ui_border	Colors for borders, rules, and gutters.	banner_border
ui_ok / ui_warn / ui_error	Status indicators (Success/Warning/Error).	None

Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:21-33, ui-tui/src/theme.ts

Creating and Managing Skins

Skins are defined as YAML files. Each file must contain a colors mapping with hex color codes in the #rrggbb format to ensure cross-platform compatibility.

Skin File Structure

---
name: synthwave
colors:
  background: "#2d0b3d"
  ui_primary: "#ff7edb"
  ui_accent: "#36f9f6"
  ui_text: "#e0e0e0"
  ui_tool: "#fede5d"
  ui_border: "#722193"
  ui_ok: "#00ff00"
  ui_warn: "#ffcc00"
  ui_error: "#ff0000"
---

Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:21-33, optional-skills/creative/auteur/templates/DESIGN.md:12-23

Procedures for Customization

1. Create a new skin: Use the write_file tool to save a YAML theme into the ~/.hermes/skins/ directory.
2. Activate a skin: Use the terminal to run hermes config set display.skin <name>. This is the safe method to update configuration; manual editing of config.yaml is discouraged as it can corrupt the file.
3. Tweak the active skin: To change a specific color without creating a new file, use hermes skin set <key> <hex>. This command patches the active skin file in place.
4. Revert to default: Run hermes config set display.skin default to return to the original Hermes appearance.

Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:35-46, hermes_cli/skin_engine.py

Design Standards and Constraints

Theme authors must adhere to specific technical constraints to ensure UI accessibility and system stability:

• Hex Codes Only: Use #rrggbb format. Shorthand like #rgb, rgb(), or named colors are not guaranteed to parse correctly across all surfaces.
• Accessibility: The ui_accent color should maintain a contrast ratio of at least 4.5:1 (WCAG AA) against the background to ensure legibility.
• Naming: Avoid naming custom skins after built-in GUI presets (e.g., mono, slate, cyberpunk, nous, midnight, ember) to prevent collisions.
• Inheritance: Missing keys in a custom skin YAML will automatically inherit values from the default skin.

Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:48-58, optional-skills/creative/auteur/templates/DESIGN.md:46-51

This sequence illustrates the live update process when a user modifies a specific theme property.
Sources: skills/autonomous-ai-agents/hermes-agent/references/themes.md:43-46

Summary

The Hermes Skin Engine provides a unified, semantic approach to theming that spans multiple application surfaces. By using the hermes config and hermes skin CLI tools, developers and users can create or modify visual identities with immediate feedback via the live repaint mechanism. Adherence to the hex-only color format and semantic key mapping is required for maintaining cross-surface compatibility and accessibility.