> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme System (Colors)

> ChatCLI's unified color palette: 11 themes (dark, light + 9 community palettes), themed markdown, and graceful degradation by terminal capability.

Since **v1.125**, every color in ChatCLI comes from a single source of truth: the `ui/theme` package. It defines a **semantic palette** (colors named by role, not by hue), detects the **terminal's color capability**, and ships **11 ready-made themes** (`dark`, `light` + 9 community palettes) that re-skin the entire UI — chat, `/coder` and `/agent` cards, borders, markdown, code blocks, and spinners — with no restart.

<Info>
  The theme is **process-global state**. Switching applies on the **next render**, no restart needed. Unlike `CHATCLI_CODER_UI` (the timeline style), which the renderer re-reads from the environment on every call.
</Info>

***

## Switch themes at runtime

```bash theme={"system"}
/config ui                     # show the active theme + detected color profile
/config ui theme               # same thing (explicit form)
/config ui theme dark          # switch to the dark theme
/config ui theme dracula       # switch to any theme by name
/config ui theme tokyo-night   # hyphenated names work fine

/config theme dracula          # shorthand equivalent to /config ui theme dracula
```

<Tip>
  Full autocomplete: type `/config ui theme <TAB>` (or `/config theme <TAB>`) and every theme appears: `dark · light · dracula · nord · tokyo-night · solarized-dark · solarized-light · gruvbox · catppuccin-mocha · monokai · one-dark`.
</Tip>

The status panel (`/config ui`) shows the active theme, the **source** of the value (environment variable vs. default), the detected **color profile**, and the list of themes with the active one marked by `→`.

***

## Available themes

There are **11 themes** in total. Each strip shows the name and the palette's **real colors**, in the order **model · accent (reasoning) · ok · warn · error**:

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=815f91edaaed571de10d41049e7ae6da" alt="dark theme" width="420" height="40" data-path="images/themes/dark.svg" /> — default, dark-background terminals

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/light.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=a00feadc08705d24c4211d92a52b2165" alt="light theme" width="420" height="40" data-path="images/themes/light.svg" /> — light-background terminals

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/dracula.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=415cbc3ebad4e8672681f7a3acee5cda" alt="dracula theme" width="420" height="40" data-path="images/themes/dracula.svg" /> — high-contrast purple/pink/cyan

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/nord.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=5bb6bc1c2f16890f8d9b90a1bc69d958" alt="nord theme" width="420" height="40" data-path="images/themes/nord.svg" /> — cool arctic, low saturation

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/tokyo-night.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=78effb64f88e8f59da6a4494e23ce853" alt="tokyo-night theme" width="420" height="40" data-path="images/themes/tokyo-night.svg" /> — modern night-blue

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/solarized-dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=0d63cd2c30533298636cf692a44dee49" alt="solarized-dark theme" width="420" height="40" data-path="images/themes/solarized-dark.svg" /> — Solarized on its dark base

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/solarized-light.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=c80ffc90a7bb5f8336b9a7e2e8e44c71" alt="solarized-light theme" width="420" height="40" data-path="images/themes/solarized-light.svg" /> — same hues on a light background

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/gruvbox.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=6b83325929fc354c6dc8762a1e360398" alt="gruvbox theme" width="420" height="40" data-path="images/themes/gruvbox.svg" /> — retro, warm, high-contrast

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/catppuccin-mocha.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=f6f36a9c166e04ad7ec1f21a288f3f6f" alt="catppuccin-mocha theme" width="420" height="40" data-path="images/themes/catppuccin-mocha.svg" /> — soft pastel (Mocha)

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/monokai.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=e9c649b29429c286ebcb456301a96fd4" alt="monokai theme" width="420" height="40" data-path="images/themes/monokai.svg" /> — classic editor palette on charcoal

<img src="https://mintcdn.com/encom/jHEV2Aj5E_4oDf2A/images/themes/one-dark.svg?fit=max&auto=format&n=jHEV2Aj5E_4oDf2A&q=85&s=87f6d59d1d880c76d475f1dd3fdc2058" alt="one-dark theme" width="420" height="40" data-path="images/themes/one-dark.svg" /> — Atom's balanced blue/gray

<Note>
  `dark` and `light` are ChatCLI's calibrated variants; the other nine are adaptations of the classic community palettes mapped onto ChatCLI's semantic roles (same structure, different colors). All of them degrade to 256 and 16 colors while keeping the roles distinguishable.
</Note>

The switch applies the palette **all at once** because `Colorize` and the `ansiColorToLip` converter route through the active theme — there's no call-site churn.

***

## Semantic palette

Colors are named by the **role** they serve, not by hue. That's what makes swapping the whole theme a matter of touching only the palette:

| Group           | Field                 | Use                                       |
| --------------- | --------------------- | ----------------------------------------- |
| Brand/Hierarchy | `Primary`             | model name, primary actions               |
|                 | `Secondary`           | multi-agent, batch, secondary badges      |
|                 | `Accent`              | reasoning / cognitive emphasis            |
|                 | `Muted`               | neutral borders, secondary text, defaults |
| Semantic state  | `Success`             | tool success, enabled                     |
|                 | `Warning`             | warnings, disabled                        |
|                 | `Danger`              | errors, tool failure                      |
|                 | `Info`                | notes / explanations                      |
| Structural      | `Border`              | default card border                       |
|                 | `Text` / `TextStrong` | body text / bold and headings             |
|                 | `Background`          | code-block background                     |

***

## Themed markdown

Markdown is rendered by glamour with a `StyleConfig` **derived from the palette** (replacing the legacy `glamour.WithStandardStyle("dark")`), so markdown and code-block colors share the UI's hues. Syntax highlighting via **chroma** and a **language chip** above each code block. The document is rendered **whole** (not block by block), so reference links, footnotes, and paragraph spacing all resolve correctly.

***

## Color profile and graceful degradation

ChatCLI detects the terminal's capability and degrades gracefully. In pipes, CI, or `dumb` terminals, output becomes **clean plain text with no color codes**.

| Profile     | Meaning                                       |
| ----------- | --------------------------------------------- |
| `TrueColor` | 24-bit terminal                               |
| `ANSI256`   | 8-bit (256-color) terminal                    |
| `ANSI`      | classic 16-color terminal (SGR 30–37 / 90–97) |
| `ASCII`     | no color — `NO_COLOR`, `dumb`, pipe/redirect  |

Detection honors the usual signals (`NO_COLOR`, `CLICOLOR_FORCE`, `TERM`, `COLORTERM`). The `dark` theme keeps the **ANSI16 = 10** index for green, so 16-color terminals are identical to legacy behavior.

***

## Persistence

A runtime switch applies only to the **current process**. To pin a default across sessions, add to your `.env`:

```bash theme={"system"}
CHATCLI_THEME=light
```

The mutator prints this hint right after each switch. ChatCLI **never rewrites your `.env`** on its own. See [`CHATCLI_THEME`](/reference/environment-variables) in the environment-variable reference.

<Note>
  Parallel change in v1.125: the chat reply envelope gained a **footer** with per-turn cost and context usage, and spinners were unified into a single themed braille spinner, shown only when a terminal is present.
</Note>