> ## Documentation Index
> Fetch the complete documentation index at: https://soulforge.proxysoul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes

> 36 builtin themes, custom themes with hot reload — pick your flavor or add yours.

## Quick start

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

## Builtin themes

### Dark

| Theme                  | Description                                  |
| ---------------------- | -------------------------------------------- |
| `dark`                 | SoulForge default                            |
| `solarized-dark`       | Ethan Schoonover's classic                   |
| `catppuccin`           | Catppuccin Mocha                             |
| `catppuccin-frappe`    | Catppuccin Frappe                            |
| `catppuccin-macchiato` | Catppuccin Macchiato                         |
| `gruvbox-dark`         | Retro groove                                 |
| `tokyo-night`          | Tokyo Night                                  |
| `tokyonight-storm`     | Tokyo Night Storm                            |
| `dracula`              | Dracula                                      |
| `nord`                 | Arctic, north-bluish                         |
| `one-dark`             | Atom One Dark                                |
| `rose-pine`            | All natural pine                             |
| `kanagawa`             | Inspired by Katsushika Hokusai               |
| `github-dark`          | GitHub Dark                                  |
| `everforest-dark`      | Comfortable green                            |
| `ayu-dark`             | Ayu Dark                                     |
| `nightfox`             | Nightfox                                     |
| `proxysoul-main`       | proxySoul — deep purple with hot pink        |
| `proxysoul-coffee`     | proxySoul Coffee — warm amber & burnt orange |
| `proxysoul-water`      | proxySoul Water — ocean blue & teal          |
| `cyberdream`           | Cyberdream                                   |
| `oxocarbon`            | Oxocarbon                                    |
| `sonokai`              | Sonokai                                      |
| `moonfly`              | Moonfly                                      |
| `melange`              | Melange                                      |
| `solarized-osaka`      | Solarized Osaka                              |
| `bamboo`               | Bamboo                                       |
| `nordic`               | Nordic                                       |
| `synthwave`            | Synthwave                                    |
| `iceberg`              | Iceberg                                      |
| `ember`                | Ember                                        |
| `vesper`               | Vesper                                       |

### Light

| Theme              | Description       |
| ------------------ | ----------------- |
| `light`            | Clean light theme |
| `catppuccin-latte` | Catppuccin Latte  |
| `one-light`        | Atom One Light    |
| `github-light`     | GitHub Light      |

## Config

Theme is saved globally in `~/.soulforge/config.json`:

```json theme={null}
{
  "theme": {
    "name": "catppuccin",
    "transparent": true,
    "userMessageOpacity": 70,
    "diffOpacity": 30,
    "borderStrength": "strong"
  }
}
```

| Field                | Description                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `name`               | Theme ID (builtin or custom)                                                                            |
| `transparent`        | Make background transparent (terminal background bleed-through)                                         |
| `userMessageOpacity` | User message background opacity when transparent: `0` (clear), `30` (dim), `70` (subtle), `100` (solid) |
| `diffOpacity`        | Diff background opacity when transparent: `0` (clear), `30` (dim), `70` (subtle), `100` (solid)         |
| `borderStrength`     | Border visibility: `"default"`, `"strong"`, or `"op"`                                                   |

### Theme picker controls

| Key       | Action                           |
| --------- | -------------------------------- |
| `↑` / `↓` | Navigate themes (live preview)   |
| `Enter`   | Apply selected theme             |
| `Tab`     | Toggle transparent mode          |
| `M`       | Cycle message background opacity |
| `D`       | Cycle diff background opacity    |
| `B`       | Cycle border strength            |

## Custom themes

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

```bash theme={null}
mkdir -p ~/.soulforge/themes
```

### Example

`~/.soulforge/themes/my-theme.json`:

```json theme={null}
{
  "_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

| Field          | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `_extends`     | Inherit from a builtin theme (default: `dark`). Only override the tokens you want to change. |
| `_label`       | Display name in the theme picker                                                             |
| `_description` | Description 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`:

```json theme={null}
{
  "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.