Themes

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:

/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:

cli.json

{
  "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:

~/.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.

my-theme.json

{
  "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.<name>.<step>, 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:

echo $COLORTERM

Most modern terminals report truecolor or 24bit. Without truecolor, OpenCode approximates theme colors using the available terminal palette.

Get started

Configure

Choose a theme

Built-in themes

Custom themes

Format

Token reference

Hue tokens

Semantic tokens

Contexts

Terminal colors

​Choose a theme

​Built-in themes

​Custom themes

​Format

​Token reference

​Hue tokens

​Semantic tokens

​Contexts

​Terminal colors

Choose a theme

Built-in themes

Custom themes

Format

Token reference

Hue tokens

Semantic tokens

Contexts

Terminal colors