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
proxysoul-mainproxySoul — deep purple with hot pink
proxysoul-coffeeproxySoul Coffee — warm amber & burnt orange
proxysoul-waterproxySoul Water — ocean blue & teal
cyberdreamCyberdream
oxocarbonOxocarbon
sonokaiSonokai
moonflyMoonfly
melangeMelange
solarized-osakaSolarized Osaka
bambooBamboo
nordicNordic
synthwaveSynthwave
icebergIceberg
emberEmber
vesperVesper

​
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,
    "userMessageOpacity": 70,
    "diffOpacity": 30,
    "borderStrength": "strong"
  }
}
FieldDescription
nameTheme ID (builtin or custom)
transparentMake background transparent (terminal background bleed-through)
userMessageOpacityUser message background opacity when transparent: 0 (clear), 30 (dim), 70 (subtle), 100 (solid)
diffOpacityDiff background opacity when transparent: 0 (clear), 30 (dim), 70 (subtle), 100 (solid)
borderStrengthBorder visibility: "default", "strong", or "op"

​
Theme picker controls

KeyAction
↑ / ↓Navigate themes (live preview)
EnterApply selected theme
TabToggle transparent mode
MCycle message background opacity
DCycle diff background opacity
BCycle border strength

​
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
  • Text: text-primary, text-secondary, text-muted, text-dim, text-faint, text-subtle
  • Backgrounds: bg-app, bg-primary, bg-secondary, bg-elevated, bg-popup, bg-popup-highlight, bg-overlay, bg-input, bg-banner, bg-banner-error, bg-user
  • Borders: border, border-focused, border-active, border-slash
  • Status: success, error, warning, info, amber
  • Diff: diff-added-bg, diff-removed-bg, diff-added-sign, diff-removed-sign
  • Accents: accent-user, accent-assistant, accent-system

​
Legacy format

You can also define multiple themes in ~/.soulforge/themes.json: 
{
  "my-theme": {
    "_extends": "dark",
    "brand": "#ff6600"
  },
  "another-theme": {
    "_extends": "light",
    "brand": "#0066ff"
  }
}

​
Hot reload

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