Skip to main content

Themes

Choose a built-in theme at launch, or add a JSON palette for your terminal.

mecatui includes three themes:

  • aztec: the default, with jade, turquoise, and gold on obsidian
  • mono: neutral grays with a blue accent
  • solar: a warm, light-leaning variant

Select one at launch:

mecatui --theme mono

You can also set MECATUI_THEME=mono. Use --list-themes to print the themes available to this launch.

Let mecatui choose for your terminal​

When you do not set --theme or MECATUI_THEME, mecatui asks an interactive terminal for its background color. It selects solar for a reported light background. A dark background, no response, or redirected output uses the default aztec theme.

Passing --theme or MECATUI_THEME, including --theme aztec, skips this detection. Pin a theme to disable automatic selection.

Aztec uses rose for model-response markers, gold for user markers, and lavender for ordinary harness notices. Solar uses saturated accents tuned for light backgrounds. Message text and success, warning, and error indicators have separate colors; reasoning is subdued and italic.

Add a partial palette​

Theme files are JSON. A palette extends the Aztec base, so it only needs the slots it changes:

{
  "name": "midnight",
  "palette": {
    "accent": "#7C5CFF",
    "primary": "#5CC8FF",
    "error": "#FF5C7C"
  }
}

Save the file in one of these locations. If the same theme name appears more than once, the later location wins:

  1. $XDG_CONFIG_HOME/mecatui/themes/ (normally ~/.config/mecatui/themes/)
  2. <workspace>/.mecatui/themes/
  3. <cwd>/.mecatui/themes/
  4. a directory passed with --theme-dir

Then choose it with --theme midnight or MECATUI_THEME=midnight. Themes are discovered at startup, so restart mecatui after adding or changing a file.

Custom palettes derive user and model-marker colors from user and assistant, and ordinary harness-marker colors from info. They use text for plain message text and textMuted for harness notices, reasoning, and statistics. Markdown continues to use the md* and syntax-color slots.

Next steps​