mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-30 10:53:34 +00:00
129 lines
4.2 KiB
Text
129 lines
4.2 KiB
Text
---
|
|
title: "Themes"
|
|
description: "Choose a built-in TUI theme or create a custom color scheme."
|
|
---
|
|
|
|
import ThemeTokens from "/snippets/generated/theme-tokens.mdx"
|
|
|
|
OpenCode includes built-in light and dark themes and can load custom themes
|
|
from your global configuration or a project directory. The default theme is
|
|
`opencode`.
|
|
|
|
## Choose a theme
|
|
|
|
In the full-screen TUI, run:
|
|
|
|
```text
|
|
/themes
|
|
```
|
|
|
|
You can also open the picker with `ctrl+x`, then `t`, using the
|
|
default keybindings.
|
|
|
|
Use `/settings` to change both the theme and its color mode. OpenCode supports
|
|
three modes:
|
|
|
|
| Mode | Behavior |
|
|
| -------- | -------------------------------------------------------- |
|
|
| `system` | Follow the terminal's detected light or dark appearance. |
|
|
| `dark` | Always use the theme's dark colors. |
|
|
| `light` | Always use the theme's light colors. |
|
|
|
|
Your selection is stored in `~/.config/opencode/cli.json`, or the equivalent
|
|
path under `$XDG_CONFIG_HOME`:
|
|
|
|
```json title="cli.json"
|
|
{
|
|
"theme": {
|
|
"name": "tokyonight",
|
|
"mode": "system"
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
Theme selection applies to the full-screen TUI. Direct interactive runs use colors derived from the terminal palette
|
|
and honor only the color mode.
|
|
</Note>
|
|
|
|
## Built-in themes
|
|
|
|
OpenCode currently includes:
|
|
|
|
| | | |
|
|
| ------------ | ------------------- | ---------------------- |
|
|
| `aura` | `ayu` | `carbonfox` |
|
|
| `catppuccin` | `catppuccin-frappe` | `catppuccin-macchiato` |
|
|
| `cobalt2` | `cursor` | `dracula` |
|
|
| `everforest` | `flexoki` | `github` |
|
|
| `gruvbox` | `kanagawa` | `lucent-orng` |
|
|
| `material` | `matrix` | `mercury` |
|
|
| `monokai` | `nightowl` | `nord` |
|
|
| `one-dark` | `opencode` | `orng` |
|
|
| `osaka-jade` | `palenight` | `rosepine` |
|
|
| `solarized` | `synthwave84` | `tokyonight` |
|
|
| `vercel` | `vesper` | `zenburn` |
|
|
|
|
When OpenCode can read your terminal palette, the picker also includes
|
|
`system`. The `system` theme generates its colors from your terminal's
|
|
foreground, background, and ANSI palette.
|
|
|
|
## Custom themes
|
|
|
|
Create a JSON file in either of these locations:
|
|
|
|
```text
|
|
~/.config/opencode/themes/my-theme.json
|
|
.opencode/themes/my-theme.json
|
|
```
|
|
|
|
OpenCode checks the global theme directory first, followed by every
|
|
`.opencode/themes` directory from the filesystem root down to the current
|
|
directory. A more local file with the same filename overrides an earlier one.
|
|
The filename becomes the theme name, so `my-theme.json` appears as `my-theme`.
|
|
|
|
Custom theme files must be strict JSON. Comments and trailing commas are not
|
|
supported.
|
|
|
|
### Format
|
|
|
|
V2 themes organize colors into hue scales and semantic tokens. Set `version`
|
|
to `2` and define at least one of `light` or `dark`:
|
|
|
|
<Warning>
|
|
Native V2 custom theme files are not loaded directly by the current beta. Existing custom files use the V1 format and
|
|
are migrated to these tokens at runtime. This reference tracks the native V2 schema while direct file loading is
|
|
completed.
|
|
</Warning>
|
|
|
|
By default, a theme inherits OpenCode's complete theme, so you only need to
|
|
define overrides. Set `mergeMode` to `true` to inherit one mode from the other
|
|
before applying that mode's overrides. Set `standalone` to `true` only when you
|
|
intend to supply a complete independent theme.
|
|
|
|
Each token accepts:
|
|
|
|
- A hex color such as `"#5c9cf5"`
|
|
- `"transparent"` to use the terminal default
|
|
- A hue reference such as `"$hue.blue.500"`
|
|
- Another semantic token reference such as `"$text.default"`
|
|
|
|
Syntax and markdown tokens accept hex colors and hue references. Other
|
|
semantic tokens can reference any semantic token.
|
|
|
|
<ThemeTokens />
|
|
|
|
If you add or edit a custom theme while OpenCode is running, restart the TUI to
|
|
reload it.
|
|
|
|
## Terminal colors
|
|
|
|
Themes display most accurately in a terminal with truecolor support. Check
|
|
your terminal with:
|
|
|
|
```bash
|
|
echo $COLORTERM
|
|
```
|
|
|
|
Most modern terminals report `truecolor` or `24bit`. Without truecolor,
|
|
OpenCode approximates theme colors using the available terminal palette.
|