All platforms · 8 min · OpenCode checked August 18, 2026

OpenCode themes and skins: install, verify, remove, restore

Install a custom OpenCode JSON theme from a themes directory, activate it, verify the live colours, remove it, and return to a built-in theme with no installer and no patched files.

Edited and reviewed by CodexTheme Tools editorial. Reviewed . First published . Status: Published. User task: Install, activate, verify, remove, and restore a custom OpenCode JSON theme file.

Sources: Official OpenCode theme documentation (themes directory locations, JSON theme files, paired dark and light values, theme selection at runtime and through the theme field): https://opencode.ai/docs/themes/. Official OpenCode repository, checked at commit 57075d8cdc1d9099c3f806d5e21ffe9c0853aae3 for the theme key list and file layout: https://github.com/anomalyco/opencode. The published theme schema reference emitted in every generated file: https://opencode.ai/theme.json. No site-owned device verification of OpenCode is claimed, and this guide is not affiliated with OpenCode.

Platform behavior can change. Compare this guide with the OpenCode repository at commit 57075d8cdc1d.

Quick answer

Save the theme as one JSON file in an OpenCode themes directory, keep the file stem as the theme name, and select it with the theme command or the theme field in configuration. Every key needs both a dark and a light value. Removing the file and clearing that setting restores a built-in theme, because nothing was installed.

01Read the theme JSON before copying it
02Copy it into the themes directory
03Activate it by file stem
04Verify, then rehearse removal

Where OpenCode looks for a theme file

A user theme is a single JSON file in a themes directory: the per-user configuration directory for a theme you want everywhere, or a project-level directory for a theme scoped to one repository. The file name matters, because the stem — the name without the .json extension — is the theme's identity in the picker and in configuration. Keep it lowercase and hyphenated, avoid spaces, and do not nest the file inside an extra folder, which is the most common reason a copied theme never appears.

Every colour is a dark and light pair

The contract does not accept a bare colour string. Each key carries an object with a dark value and a light value, so one file covers both appearances and the client picks the side it needs. That is also why a theme file is longer than people expect: alongside the obvious background, text, and border roles, the contract names diff colours, diff line-number backgrounds, markdown roles, and syntax roles. Leaving those out means the parts you read most keep inherited colours that may not survive your surfaces.

Inspect the file before you keep it

A theme file is data, which is exactly why it should be boring to read. Open it and confirm you see a schema reference and a theme object of hex pairs and nothing else: no URL to fetch, no script, no path, no command, no credential. A JSON file cannot install itself, and a website that generates one cannot copy it, activate it, or run anything on your machine. If a download claims otherwise, or arrives as an archive containing an executable, do not extract it into your configuration directory.

Activate the theme by its file stem

With the file in place, select the theme inside OpenCode with its theme command, or set the theme field in the TUI configuration to the same stem so it survives a restart. Do not rename the file and expect the old name to keep working; the stem is the identifier. If the entry does not appear, check the directory, the file extension, and whether the JSON parses at all before changing any colours.

Verify with the file open beside the client

Compare live surfaces against the values you wrote, not against a screenshot. Check the transcript background, a raised panel, a border, a focused border, muted text, and then the parts a background change usually breaks: added and removed diff lines, diff line numbers, inline code, comments, strings, and type names. Read compact metadata as well as headings, because a palette can look correct at large sizes and fail on the smallest text in the interface.

Remove the theme and restore a built-in one

Removal is deleting the file you copied and selecting a built-in theme again; also clear the theme field if you set it in configuration. There is no uninstaller, no leftover state, and no cache to clear, because nothing was installed. With the file gone and the setting empty, OpenCode uses its own default theme exactly as it did before. Delete the file only when you no longer need to inspect it.

When an upstream change breaks the theme

A theme written against one version can lose keys, gain keys, or apply partially after an update. Diagnose in order: confirm the client works with a built-in theme, confirm your file still parses, then compare your key list against the current contract and fill in anything new. Re-read the contract and regenerate rather than forcing an old file to load, and never patch the client itself to make a colour stick.

A valid JSON file is not a compatibility certificate. The key list here was read at one commit; re-check the current contract after an update, and never extract an archive that contains a script or executable into your configuration directory.

Completion checklist

Frequently asked questions

Where do I put a custom OpenCode theme?

In a themes directory: the per-user configuration directory for a theme available everywhere, or a project-level themes directory for one repository. The file goes directly inside it, not in a nested subfolder, and the file stem becomes the theme name.

Why does my OpenCode theme not appear in the picker?

Usually the file is nested one level too deep, the extension is wrong, the JSON does not parse, or the stem is not what you are searching for. Confirm those four things before editing colours, and check that the client is reading the configuration directory you expect.

Why does every colour need two values?

The contract stores a dark and a light value per key so one file covers both appearances. A bare colour string is not a valid entry, which is why a generated theme always emits pairs.

How do I get the default theme back?

Delete the file you copied, clear the theme field if you set it, and select a built-in theme. Nothing else needs cleaning up: a theme file is data, so no installer, service, or cached state was created.

Related guides