Gemini CLI: Standalone theme.json for Custom Themes
Gemini CLI v0.69.0 now discovers custom themes from a standalone theme.json file, so color palettes no longer have to live inside settings.json. The CLI checks ~/.gemini/theme.json and the XDG config path automatically. This suits palette generators such as wallust, pywal and matugen.
Key Takeaways
- Gemini CLI now auto-discovers a standalone
theme.jsonfile for custom themes. - It checks
~/.gemini/theme.jsonand the XDG config path (~/.config/gemini/theme.json). - The design targets palette generators like wallust, pywal and matugen, which can rewrite one file safely.
- On name conflicts,
~/.gemini/theme.jsonwins over the XDG path and inlineui.customThemes. - The file can hold a single theme or a map of named themes.
- The feature shipped in v0.69.0 (stable, 2026-11-19) alongside
/stats heatmap.
Custom themes without touching settings.json
Gemini CLI v0.69.0, released on November 19, 2026, added support for standalone theme.json configurations for custom themes. Previously, custom themes were defined in the ui.customThemes object of settings.json. The new file lets users keep their color palette separate from behavioral settings.
The Gemini CLI documentation says the goal is to keep dynamic color palettes, for example those generated by tools like wallust, pywal or matugen, decoupled from settings.json. A palette generator can rewrite one file without risking the rest of the user's configuration.
Where Gemini CLI looks
Gemini CLI discovers custom themes automatically in two locations:
~/.gemini/theme.json(or$GEMINI_CLI_HOME/.gemini/theme.json)$XDG_CONFIG_HOME/gemini/theme.json, falling back to~/.config/gemini/theme.json
If the same theme name appears in more than one place, ~/.gemini/theme.json takes precedence over the XDG path and over inline ui.customThemes in settings.json.
File format
A theme.json can contain either a single theme object or a map of named themes. Each theme declares a name, a type of custom, and color groups such as background.primary and text.primary and text.secondary. The same structure as inline custom themes applies, and users can still point the ui.theme setting at a theme file path directly to share themes between machines.
Why it matters
Terminal users who theme their whole desktop from a wallpaper can now have Gemini CLI follow along automatically. It also makes themes easier to share and version separately from personal settings.