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.
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.
Completion checklist
- The theme JSON was read before copying
- The file sits directly in a themes directory with a stem you chose
- Every key carries both a dark and a light value
- Diff, markdown, and syntax colours were checked live
- Deleting the file and clearing the setting restores a built-in theme
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.