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:

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

Your selection is stored in ~/.config/opencode/cli.json, or the equivalent path under $XDG_CONFIG_HOME:

{
  "theme": {
    "name": "tokyonight",
    "mode": "system"
  }
}

Built-in themes

OpenCode currently includes:

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:

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.

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

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.

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.