10. Configuration, Themes, and Terminals

Themes

Change the fullscreen color palette. /theme exists only in fullscreen: minimal mode paints with your terminal’s own colors and ignores theme settings.

Built-in palettes

Names are case-insensitive. Canonical ids (what Matcha writes) are in backticks.

Display	Canonical	Also accepted	Truecolor
Matcha Night	`matchanight`	`matcha-night`, `dark`, `groknight`, `grok-night`	No
Matcha Day	`matchaday`	`matcha-day`, `light`, `day`, `grokday`, `grok-day`	No
Tokyo Night	`tokyonight`	`tokyo-night`, `tokyo`	Yes
Rose Pine Moon	`rosepine-moon`	`rosepine`, `rose-pine`, `rose-pine-moon`	Yes
Oscura Midnight	`oscura-midnight`	`oscura`	Yes

Matcha Night is the default. It quantizes cleanly on 256-color and 16-color terminals. Tokyo Night, Rose Pine Moon, and Oscura Midnight need 24-bit color; /doctor hides them from the picker when truecolor is missing, but /theme tokyonight is still accepted and the live colors are clamped.

auto (alias system) follows the OS light/dark appearance. It is not a palette of its own.

Switch in the TUI

Fullscreen only:

Type /theme (alias /t).
Move through the list. Each row previews without writing disk.
Press Enter to apply and save, or Escape to restore the previous theme.

Other forms:

/theme tokyonight
/theme auto
/theme

A name applies that palette (or auto). /theme with no argument cycles to the next concrete theme among those available on this terminal.

Persist in config.toml

The palette lives in ~/.matcha/config.toml, not in pager.toml:

[ui]
theme = "tokyonight"

pager.toml controls padding, scrollbar, animation, and [terminal] alt_screen. It has no theme key.

Compact mode (/compact-mode) is a separate [ui] compact_mode flag: less padding, same palette.

Follow the OS

[ui]
theme = "auto"
auto_dark_theme = "tokyonight"
auto_light_theme = "matchaday"

Defaults: dark → Matcha Night, light → Matcha Day. You can also set the two mappings from /settings → Appearance → Auto dark theme / Auto light theme. Picking auto in the /theme picker turns auto mode on using those mappings. Picking a named theme turns auto mode off.

Detection:

Where	How
macOS	`AppleInterfaceStyle`
Linux	XDG Desktop Portal color-scheme
Windows	Personalization registry
SSH / tmux / headless	Env stamps, then `COLORFGBG`, then a startup OSC 11 query

On a local desktop, Matcha polls about every 5 seconds, so flipping the OS appearance updates the TUI without a restart. Over SSH the wrap-stamped value is fixed for that hop.

matcha wrap ssh … stamps LC_GROK_APPEARANCE from the local OS so a remote theme = "auto" can resolve. New tmux sessions inherit that only if the tmux server was created with the env (or update-environment includes it).

Environment override

Registered product names are MATCHA_THEME and MATCHA_APPEARANCE (legacy GROK_* when the Matcha name is unset).

Color support

On startup Matcha detects truecolor, 256-color, or 16-color, then quantizes every theme slot (and runtime syntax colors) to that level. NO_COLOR turns color off.

Run /doctor and look for color truecolor and themes all. Inside tmux, Matcha can emit 24-bit color while tmux rewrites it; that is terminal.tmux-truecolor. See Terminal support.

Matcha also sets the terminal cursor to the theme accent (OSC 12) and resets it on exit (OSC 112) on terminals that support those sequences.

Check your work

In fullscreen, /theme → preview Matcha Day → Enter. Confirm ~/.matcha/config.toml has [ui] theme = "matchaday" (canonical matchaday).
/theme auto, then flip the OS appearance and wait a few seconds.
/minimal, type /theme, and confirm the refusal. /fullscreen to return.