Custom themes

Step Code includes six themes and supports custom colors in JSON. Place a file in a theme directory to select it in /theme. Editing the active theme reloads it immediately.

Built-in themes

Theme	Purpose
`step-blue`	Default blue theme
`step-violet`	Purple for dark terminals
`step-violet-light`	Purple for light terminals
`dark`, `light`	General dark and light themes
`sage`	Green for dark terminals

Theme files

Scope	Path
User	`~/.stepcode/agent/themes/*.json`
Project	`.stepcode/themes/*.json`; requires trust
Package	Theme directory in a resource package
Launch option	`--theme <path>`, repeatable

The filename is the theme name, such as my-theme.json. Custom themes appear alongside built-in themes in /theme. Start from a complete theme and retain all color fields while adjusting the palette.

Theme JSON format

A theme has name, reusable vars, and a colors mapping. This example illustrates fields; it is not a complete replacement theme:

{
  "name": "my-theme",
  "vars": {"primary": "#7aa2f7"},
  "colors": {
    "accent": "primary",
    "text": "#c0caf5",
    "mdTableHeader": "#9d7cd8",
    "syntaxKeyword": "#bb9af7"
  }
}

A complete theme defines all 52 color tokens, covering core UI, backgrounds and content, Markdown, diffs, syntax highlighting, thinking borders, and bashMode. The partial example above cannot be used as a complete theme.

Value	Meaning
`"#ff0000"`	Six-digit hexadecimal color
`39`	xterm 256-color index
`"primary"`	Reference a variable in `vars`
`""`	Use the terminal default

True-color terminals use 24-bit colors; others may fall back to nearby 256-color values. Use brighter, saturated colors on dark terminals and darker, muted colors on light terminals. Put shared base colors in vars.

Switching themes

/theme
/theme my-theme

Set the default in configuration:

theme = "my-theme"

For one launch only:

step --use-theme light

/theme opens the picker; custom themes are available without restarting. /theme <name> switches directly. Editing the active file hot-reloads it.

statusTips

statusTips is a boolean in config.toml, not a theme field. It defaults to true, showing one working-line tip per turn. Disable it with:

statusTips = false

Error behavior

Invalid colors fail the entire theme and fall back to built-in dark. A transient error during hot reload retains the active theme. Check JSON syntax, color values, variable references, and field completeness.

Guides

Configuration

Customization

Reference

Built-in themes

Theme files

Theme JSON format

Switching themes

statusTips

Error behavior

Next steps

​Built-in themes

​Theme files

​Theme JSON format

​Switching themes

​statusTips

​Error behavior

​Next steps

Built-in themes

Theme files

Theme JSON format

Switching themes

statusTips

Error behavior

Next steps