Skip to main content

​
Quick start

Press /theme or Ctrl+K → search “theme” to open the theme picker. Themes preview live as you navigate.

​
Builtin themes

​
Dark

ThemeDescription
darkSoulForge default
solarized-darkEthan Schoonover’s classic
catppuccinCatppuccin Mocha
catppuccin-frappeCatppuccin Frappe
catppuccin-macchiatoCatppuccin Macchiato
gruvbox-darkRetro groove
tokyo-nightTokyo Night
tokyonight-stormTokyo Night Storm
draculaDracula
nordArctic, north-bluish
one-darkAtom One Dark
rose-pineAll natural pine
kanagawaInspired by Katsushika Hokusai
github-darkGitHub Dark
everforest-darkComfortable green
ayu-darkAyu Dark
nightfoxNightfox

​
Light

ThemeDescription
lightClean light theme
catppuccin-latteCatppuccin Latte
one-lightAtom One Light
github-lightGitHub Light

​
Config

Theme is saved globally in ~/.soulforge/config.json: 
{
  "theme": {
    "name": "catppuccin",
    "transparent": true
  }
}
FieldDescription
nameTheme ID (builtin or custom)
transparentMake background transparent (terminal background bleed-through)
Toggle transparency with Tab in the theme picker.

​
Custom themes

Create your own theme by adding a JSON file to ~/.soulforge/themes/: 
mkdir -p ~/.soulforge/themes

​
Example

~/.soulforge/themes/my-theme.json: 
{
  "_extends": "dark",
  "_label": "My Theme",
  "_description": "A custom dark theme",
  "_variant": "dark",
  "brand": "#ff6600",
  "brand-secondary": "#ff0040",
  "bg-primary": "#1a1a2e",
  "bg-elevated": "#16213e",
  "text-primary": "#e0e0e0",
  "success": "#00ff88",
  "error": "#ff4444"
}
The file name (minus .json) becomes the theme ID.

​
Metadata fields

FieldDescription
_extendsInherit from a builtin theme (default: dark). Only override the tokens you want to change.
_labelDisplay name in the theme picker
_descriptionDescription shown in the picker
_variant"dark" or "light" — controls the indicator in the picker

​
Token reference

Tokens use kebab-case in JSON files (auto-converted to camelCase internally):
  • Brand: brand, brand-secondary, brand-dim, brand-alt
  • Backgrounds: bg-primary, bg-elevated, bg-sunken
  • Text: text-primary, text-secondary, text-muted, text-dim, text-faint
  • Borders: border, border-dim
  • Status: success, error, warning, info
  • Diff: diff-add, diff-remove, diff-change

​
Hot reload

Theme files are watched for changes. Edit a custom theme file and the UI updates instantly — no restart needed.