Customization

Arcana is deeply customizable. Change the theme, switch the interface voice, add a background image, or configure the TUI to match your workflow.

Themes

Arcana ships with 21 built-in themes. Switch with /theme in the TUI or via CLI:

# Set theme
arcana theme set --name dragon

# List all themes
arcana theme list

# Preview without saving
arcana theme preview lich

Available themes: arcana (default), bloodmoon, coven, crypt, dragon, grimoire, jade, lich, oracle, sakura, wraith

Custom Themes

Drop a theme JSON file into any of these directories:

Precedence: built-in < plugin-provided < custom files. Project themes override global themes of the same name. Custom themes are picked up automatically — no restart needed.

Theme Schema

A theme JSON has a defs block (named color references) and a theme block mapping ~75 tokens to { "dark": ..., "light": ... } variants:

{
  "defs": {
    "bg": "#0a0a0a",
    "accent": "#B38CFF"
  },
  "theme": {
    "text": { "dark": "#ffffff", "light": "#14110d" },
    "surface": { "dark": "#191919", "light": "#ffffff" },
    "accent": { "dark": "$accent", "light": "$accent" }
  }
}

Missing tokens fall back safely. A contrast floor is applied automatically (body text ≥ 7:1, muted ≥ 4.5:1).

Interface Voice (Lexicon)

The interface copy ships in two voices:

Switch with:

# Via CLI
arcana lexicon set --name plain

# Or in ~/.config/arcana/tui.json
{
  "theme": "dragon",
  "lexicon": "plain"
}

Restart Arcana to apply. The brand layer (sigils, theme names, wordmark) is unchanged in either voice.

Background Image

Set a custom full-screen background image in truecolor terminals (Kitty, iTerm2, WezTerm, Windows Terminal):

{
  "background": {
    "enabled": true,
    "image": "~/wallpapers/space.png",
    "opacity": 0.4,
    "fit": "cover"
  }
}

Shows on the home screen and empty areas. Falls back to the theme color where unsupported.

TUI Configuration

TUI-specific settings live in ~/.config/arcana/tui.json:

{
  "theme": "dragon",
  "lexicon": "plain",
  "background": {
    "enabled": true,
    "image": "~/wallpapers/space.png",
    "opacity": 0.4
  },
  "voice": {
    "enabled": true,
    "auto_submit": true
  }
}

arcana.json

The main configuration file. Project config deep-merges over global config:

Unknown top-level keys are rejected. Config is loaded once at startup — restart after changes.

Escape Hatches

If config is broken:

# Start from globals only (ignore project config)
ARCANA_DISABLE_PROJECT_CONFIG=1 arcana

# Use a specific config file
ARCANA_CONFIG=/path/to/config.json arcana

# Skip external plugins
ARCANA_PURE=1 arcana

Quick Reference

Related