orchestra Custom themes
Create your own palette in a JSON file and use it beside the built-in themes.
On this page
Where themes liveFile formatWhat each color controlsLight, Dark, and ANSI colorsSelect and reload a themeWhen a theme is skippedWhere themes live
Each custom theme is a folder in ~/.orchestra/themes with a theme.json file inside, for example ~/.orchestra/themes/harbor/theme.json.
The folder name identifies the theme. Custom themes are listed in a separate Custom section of the theme picker and never replace a built-in theme, even when a folder has the same name as one.
File format
theme.json uses the same shape as Orchestra’s built-in themes. light and dark are required and each list eight #RRGGBB colors, in this order: canvas, sidebar, surface, text, muted, rule, accent, selection.
name is optional; without it, the folder name is used, so harbor-lights becomes “Harbor Lights”. ansi is optional and lists 16 terminal colors.
{
"name": "Harbor",
"light": ["#F6F8F7", "#ECF1EF", "#FFFFFF", "#1D2B2A", "#5B6B69", "#D3DDDA", "#0F7B6C", "#D6ECE7"],
"dark": ["#0F1A1C", "#132124", "#1A2C30", "#DCE7E4", "#93A8A4", "#2A3F43", "#3CC7B0", "#1D3D3B"],
"ansi": [
"#1A2C30", "#E06C75", "#98C379", "#E5C07B", "#61AFEF", "#C678DD", "#3CC7B0", "#DCE7E4",
"#5B6B69", "#EF7B84", "#A8D78C", "#F3CF91", "#7BC0F5", "#D28DE7", "#78D8C8", "#FFFFFF"
]
}What each color controls
| Color | Used for |
|---|---|
canvas | The window, pages, dialogs, fields, and the terminal background. |
sidebar | The sidebar and the Changes pane. |
surface | Cards, menus, table headers, chips, and hovered controls. |
text | Primary text and the terminal’s text and cursor. |
muted | Secondary text, captions, icons, and placeholders. |
rule | Borders, dividers, and field outlines. |
accent | Primary buttons, links, focus rings, and selected markers. Button text is black or white, whichever reads better on it. |
selection | Selected and hovered rows and the terminal’s text selection. |
Status colors, such as open and merged pull requests or errors, and agent logos keep their own colors in every theme.
Light, Dark, and ANSI colors
Orchestra uses the light palette in Light mode and the dark palette in Dark mode, so switching modes keeps your theme. Both palettes are required.
ansi sets the terminal’s 16 colors in Dark mode, in the order black, red, green, yellow, blue, magenta, cyan, white, then their bright variants. Without it, Orchestra’s default terminal colors are used. In Light mode, the terminal uses Orchestra’s light ANSI colors, as built-in themes do. Changes added and removed lines use the terminal green and red.
Select and reload a theme
Choose the theme in Settings → Appearance → Theme, or press ⌘K and choose Change Theme…. Custom themes are marked Custom in the command bar.
Orchestra reads the folder again whenever Settings or the command bar opens and when the window becomes active, so you can edit theme.json and switch back to Orchestra to see the change without restarting. If the selected theme’s folder is removed or the theme becomes invalid, Orchestra switches to the System theme.
When a theme is skipped
A theme that cannot be loaded is left out of the picker; the other themes keep working. Settings → Appearance lists each skipped folder with the reason, for example:
harbor: missing theme.json.harbor: theme.json is not valid JSONharbor: "dark" is required.harbor: "light" needs 8 colors, found 7.harbor: "light" color 7 ("teal") is not a #RRGGBB hex color.
Colors must be six-digit hex values such as #0F7B6C. Files and folders whose names start with a dot are ignored.