diff --git a/docs/cli/themes.md b/docs/cli/themes.md index 6ffe5cc26a..8dda0146eb 100644 --- a/docs/cli/themes.md +++ b/docs/cli/themes.md @@ -54,7 +54,7 @@ used in the CLI. Add a `customThemes` block to your user, project, or system `settings.json` file. Each custom theme is defined as an object with a unique name and a set of -color keys. For example: +nested configuration objects. For example: ```json { @@ -63,50 +63,52 @@ color keys. For example: "MyCustomTheme": { "name": "MyCustomTheme", "type": "custom", - "Background": "#181818", - ... + "background": { + "primary": "#181818" + }, + "text": { + "primary": "#f0f0f0", + "secondary": "#a0a0a0" + } } } } } ``` -**Color keys:** +**Configuration objects:** -- `Background` -- `Foreground` -- `LightBlue` -- `AccentBlue` -- `AccentPurple` -- `AccentCyan` -- `AccentGreen` -- `AccentYellow` -- `AccentRed` -- `Comment` -- `Gray` -- `DiffAdded` (optional, for added lines in diffs) -- `DiffRemoved` (optional, for removed lines in diffs) - -You can also override individual UI text roles by adding a nested `text` object. -This object supports the keys `primary`, `secondary`, `link`, `accent`, and -`response`. When `text.response` is provided it takes precedence over -`text.primary` for rendering model responses in chat. +- **`text`**: Defines text colors. + - `primary`: The default text color. + - `secondary`: Used for less prominent text. + - `link`: Color for URLs and links. + - `accent`: Used for highlights and emphasis. + - `response`: Precedence over `primary` for rendering model responses. +- **`background`**: Defines background colors. + - `primary`: The main background color of the UI. + - `diff.added`: Background for added lines in diffs. + - `diff.removed`: Background for removed lines in diffs. +- **`border`**: Defines border colors. + - `default`: The standard border color. + - `focused`: Border color when an element is focused. +- **`status`**: Colors for status indicators. + - `success`: Used for successful operations. + - `warning`: Used for warnings. + - `error`: Used for errors. +- **`ui`**: Other UI elements. + - `comment`: Color for code comments. + - `symbol`: Color for code symbols and operators. + - `gradient`: An array of colors used for gradient effects. **Required properties:** - `name` (must match the key in the `customThemes` object and be a string) - `type` (must be the string `"custom"`) -- `Background` -- `Foreground` -- `LightBlue` -- `AccentBlue` -- `AccentPurple` -- `AccentCyan` -- `AccentGreen` -- `AccentYellow` -- `AccentRed` -- `Comment` -- `Gray` + +While all sub-properties are technically optional, we recommend providing at +least `background.primary`, `text.primary`, `text.secondary`, and the various +accent colors via `text.link`, `text.accent`, and `status` to ensure a cohesive +UI. You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names (e.g., `coral`, `teal`, `blue`) for any color value. See @@ -141,22 +143,35 @@ custom theme defined in `settings.json`. ```json { - "name": "My File Theme", + "name": "Gruvbox Dark", "type": "custom", - "Background": "#282A36", - "Foreground": "#F8F8F2", - "LightBlue": "#82AAFF", - "AccentBlue": "#61AFEF", - "AccentPurple": "#BD93F9", - "AccentCyan": "#8BE9FD", - "AccentGreen": "#50FA7B", - "AccentYellow": "#F1FA8C", - "AccentRed": "#FF5555", - "Comment": "#6272A4", - "Gray": "#ABB2BF", - "DiffAdded": "#A6E3A1", - "DiffRemoved": "#F38BA8", - "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] + "background": { + "primary": "#282828", + "diff": { + "added": "#2b3312", + "removed": "#341212" + } + }, + "text": { + "primary": "#ebdbb2", + "secondary": "#a89984", + "link": "#83a598", + "accent": "#d3869b" + }, + "border": { + "default": "#3c3836", + "focused": "#458588" + }, + "status": { + "success": "#b8bb26", + "warning": "#fabd2f", + "error": "#fb4934" + }, + "ui": { + "comment": "#928374", + "symbol": "#8ec07c", + "gradient": ["#cc241d", "#d65d0e", "#d79921"] + } } ``` @@ -180,6 +195,15 @@ untrusted sources. same [configuration precedence](../get-started/configuration.md) as other settings. +### Themes from extensions + +[Extensions](../extensions/reference.md#themes) can also provide custom themes. +Once an extension is installed and enabled, its themes are automatically added +to the selection list in the `/theme` command. + +Themes from extensions appear with the extension name in parentheses to help you +identify their source, for example: `shades-of-green (green-extension)`. + --- ## Dark themes diff --git a/docs/extensions/index.md b/docs/extensions/index.md index ae66ce07bf..64171e1c18 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -1,8 +1,8 @@ # Gemini CLI extensions -Gemini CLI extensions package prompts, MCP servers, custom commands, hooks, -sub-agents, and agent skills into a familiar and user-friendly format. With -extensions, you can expand the capabilities of Gemini CLI and share those +Gemini CLI extensions package prompts, MCP servers, custom commands, themes, +hooks, sub-agents, and agent skills into a familiar and user-friendly format. +With extensions, you can expand the capabilities of Gemini CLI and share those capabilities with others. They are designed to be easily installable and shareable. diff --git a/docs/extensions/reference.md b/docs/extensions/reference.md index c969e7a3f8..4fc94dd162 100644 --- a/docs/extensions/reference.md +++ b/docs/extensions/reference.md @@ -172,6 +172,9 @@ The file has the following structure: `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config. +- `themes`: An array of custom themes provided by the extension. Each theme is + an object that defines the color scheme for the CLI UI. See the + [Themes guide](../cli/themes.md) for more details on the theme format. When Gemini CLI starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes @@ -302,6 +305,50 @@ extension's root folder and add your agent definition files (`.md`) there. Gemini CLI will automatically discover and load these agents when the extension is installed and enabled. +### Themes + +Extensions can provide custom themes to personalize the CLI UI. Themes are +defined in the `themes` array in `gemini-extension.json`. + +**Example** + +```json +{ + "name": "my-green-extension", + "version": "1.0.0", + "themes": [ + { + "name": "shades-of-green", + "type": "custom", + "background": { + "primary": "#1a362a" + }, + "text": { + "primary": "#a6e3a1", + "secondary": "#6e8e7a", + "link": "#89e689" + }, + "status": { + "success": "#76c076", + "warning": "#d9e689", + "error": "#b34e4e" + }, + "border": { + "default": "#4a6c5a" + }, + "ui": { + "comment": "#6e8e7a" + } + } + ] +} +``` + +Custom themes provided by extensions can be selected using the `/theme` command +or by setting the `ui.theme` property in your `settings.json` file. Note that +when referring to a theme from an extension, the extension name is appended to +the theme name in parentheses, e.g., `shades-of-green (my-green-extension)`. + ### Conflict resolution Extension commands have the lowest precedence. When a conflict occurs with user diff --git a/docs/extensions/writing-extensions.md b/docs/extensions/writing-extensions.md index 0601d02231..589d9c2211 100644 --- a/docs/extensions/writing-extensions.md +++ b/docs/extensions/writing-extensions.md @@ -21,6 +21,7 @@ Extensions offer a variety of ways to customize Gemini CLI. | **[Context file (`GEMINI.md`)](reference.md#contextfilename)** | A markdown file containing instructions that are loaded into the model's context at the start of every session. | Use this to define the "personality" of your extension, set coding standards, or provide essential knowledge that the model should always have. | CLI provides to model | | **[Agent skills](../cli/skills.md)** | A specialized set of instructions and workflows that the model activates only when needed. | Use this for complex, occasional tasks (like "create a PR" or "audit security") to avoid cluttering the main context window when the skill isn't being used. | Model | | **[Hooks](../hooks/index.md)** | A way to intercept and customize the CLI's behavior at specific lifecycle events (e.g., before/after a tool call). | Use this when you want to automate actions based on what the model is doing, like validating tool arguments, logging activity, or modifying the model's input/output. | CLI | +| **[Custom themes](reference.md#themes)** | A set of color definitions to personalize the CLI UI. | Use this to provide a unique visual identity for your extension or to offer specialized high-contrast or thematic color schemes. | User (via /theme) | ## Step 1: Create a new extension diff --git a/packages/cli/src/commands/extensions/examples/themes-example/README.md b/packages/cli/src/commands/extensions/examples/themes-example/README.md index b8eb87229c..aaac7f6c38 100644 --- a/packages/cli/src/commands/extensions/examples/themes-example/README.md +++ b/packages/cli/src/commands/extensions/examples/themes-example/README.md @@ -10,11 +10,14 @@ This is an example of a Gemini CLI extension that adds a custom theme. gemini extensions link packages/cli/src/commands/extensions/examples/themes-example ``` -2. Set the theme in your settings file (`~/.gemini/config.yaml`): +2. Set the theme in your settings file (`~/.gemini/settings.json`): - ```yaml - ui: - theme: 'shades-of-green-theme (themes-example)' + ```json + { + "ui": { + "theme": "shades-of-green (themes-example)" + } + } ``` Alternatively, you can set it through the UI by running `gemini` and then diff --git a/packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json b/packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json index 47a26c5105..a526d57bf8 100644 --- a/packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json +++ b/packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json @@ -3,7 +3,7 @@ "version": "1.0.0", "themes": [ { - "name": "shades-of-green-theme", + "name": "shades-of-green", "type": "custom", "background": { "primary": "#1a362a"