> ## Documentation Index
> Fetch the complete documentation index at: https://v2.opencode.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Themes
> Choose a built-in TUI theme or create a custom color scheme.
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 theme={null}
/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={null}
{
"theme": {
"name": "tokyonight",
"mode": "system"
}
}
```
Theme selection applies to the full-screen TUI. Direct interactive runs use colors derived from the terminal palette
and honor only the color mode.
## 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 theme={null}
~/.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`:
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.
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.
```json title="my-theme.json" theme={null}
{
"version": 2,
"light": {
"hue": {
"accent": "$hue.purple",
"interactive": "$hue.purple"
},
"text": {
"default": "$hue.neutral.900"
},
"background": {
"default": "#fafafa"
}
},
"dark": {
"mergeMode": true,
"text": {
"default": "$hue.neutral.100"
},
"background": {
"default": "#101014"
}
}
}
```
## Token reference
This reference is generated from the Effect schema in
`packages/tui/src/theme/v2/schema.ts`. Changes to the runtime schema update
this section through `bun run generate`.
### Hue tokens
Every hue is a 9-step scale. Define a scale with all of these
steps, or alias it to another hue with a value such as `$hue.blue`.
| | Values |
| ----- | -------------------------------------------------------------------------------------------------------- |
| Hues | `gray`, `red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, `accent`, `interactive`, `neutral` |
| Steps | `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900` |
Reference a hue color as `$hue..`, for example
`$hue.interactive.500`.
### Semantic tokens
Semantic values can reference another token by prefixing its path with `$`,
for example `$text.default`. Stateful tokens inherit their `default`
value when a state is omitted.
| Group | Tokens |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | `text.default`
`text.subdued` |
| `text.action` | `text.action.primary.default`
`text.action.primary.$hovered`
`text.action.primary.$focused`
`text.action.primary.$pressed`
`text.action.primary.$selected`
`text.action.primary.$disabled`
`text.action.destructive.default`
`text.action.destructive.$hovered`
`text.action.destructive.$focused`
`text.action.destructive.$pressed`
`text.action.destructive.$selected`
`text.action.destructive.$disabled` |
| `text.formfield` | `text.formfield.default`
`text.formfield.$hovered`
`text.formfield.$focused`
`text.formfield.$pressed`
`text.formfield.$selected`
`text.formfield.$disabled` |
| `text.feedback` | `text.feedback.error.default`
`text.feedback.error.subdued`
`text.feedback.warning.default`
`text.feedback.warning.subdued`
`text.feedback.success.default`
`text.feedback.success.subdued`
`text.feedback.info.default`
`text.feedback.info.subdued` |
| `background` | `background.default` |
| `background.surface` | `background.surface.offset`
`background.surface.overlay` |
| `background.action` | `background.action.primary.default`
`background.action.primary.$hovered`
`background.action.primary.$focused`
`background.action.primary.$pressed`
`background.action.primary.$selected`
`background.action.primary.$disabled`
`background.action.destructive.default`
`background.action.destructive.$hovered`
`background.action.destructive.$focused`
`background.action.destructive.$pressed`
`background.action.destructive.$selected`
`background.action.destructive.$disabled` |
| `background.formfield` | `background.formfield.default`
`background.formfield.$hovered`
`background.formfield.$focused`
`background.formfield.$pressed`
`background.formfield.$selected`
`background.formfield.$disabled` |
| `background.feedback` | `background.feedback.error.default`
`background.feedback.warning.default`
`background.feedback.success.default`
`background.feedback.info.default` |
| `border` | `border.default` |
| `scrollbar` | `scrollbar.default` |
| `diff.text` | `diff.text.added`
`diff.text.removed`
`diff.text.context`
`diff.text.hunkHeader` |
| `diff.background` | `diff.background.added`
`diff.background.removed`
`diff.background.context` |
| `diff.highlight` | `diff.highlight.added`
`diff.highlight.removed` |
| `diff.lineNumber` | `diff.lineNumber.text`
`diff.lineNumber.background.added`
`diff.lineNumber.background.removed` |
| `syntax` | `syntax.comment`
`syntax.keyword`
`syntax.function`
`syntax.variable`
`syntax.string`
`syntax.number`
`syntax.type`
`syntax.operator`
`syntax.punctuation` |
| `markdown` | `markdown.text`
`markdown.heading`
`markdown.link`
`markdown.linkText`
`markdown.code`
`markdown.blockQuote`
`markdown.emphasis`
`markdown.strong`
`markdown.horizontalRule`
`markdown.listItem`
`markdown.listEnumeration`
`markdown.image`
`markdown.imageText`
`markdown.codeBlock` |
### Contexts
`@context:elevated` and `@context:overlay` accept partial
overrides of the semantic tokens above. Components apply these contexts to
surfaces that need different contrast without changing the base theme.
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 theme={null}
echo $COLORTERM
```
Most modern terminals report `truecolor` or `24bit`. Without truecolor,
OpenCode approximates theme colors using the available terminal palette.