---
title: Customization
url: https://arcana.otnelhq.com/docs/customization
---

New in v0.4.0 

Interface voice (lexicon), background images, and expanded theme system.

# 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:

```bash
# 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:

| Scope | Path |
| --- | --- |
| Global | `~/.config/arcana/themes/<name>.json` |
| Project | `.arcana/themes/<name>.json` (walked up to filesystem root) |

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:

```json
{
  "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:

| Voice | Style | Example |
| --- | --- | --- |
| `arcane` (default) | Occult verbs | *scrying*, *invoking*, *glyphs* |
| `plain` | Plain language | *reading*, *running*, *tokens* |

Switch with:

```bash
# 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):

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

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | `false` | Enable background image |
| `image` | string | — | Path to PNG/JPEG image |
| `opacity` | number | `0.4` | Image opacity (0–1). Dims image so text stays readable |
| `fit` | string | `cover` | `cover`, `contain`, or `stretch` |

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`:

```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:

| Scope | Path |
| --- | --- |
| Project | `./arcana.json`, `./arcana.jsonc`, or `.arcana/arcana.json` |
| Global | `~/.config/arcana/arcana.json` |

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

### Escape Hatches

If config is broken:

```bash
# 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

| I want to... | Do this |
| --- | --- |
| Pick a theme | `/theme` or `arcana theme set --name <name>` |
| Add my own theme | Drop a theme JSON in `.arcana/themes/` |
| Switch the interface voice | `arcana lexicon set --name plain` |
| Add a background image | Configure `background` in `tui.json` |
| Use voice input | Press `Ctrl+X V`; configure in `tui.json` |
| Change models, agents, skills | Edit `arcana.json` and restart |

## Related

- [Themes](/docs/themes) — Visual preview of all 21 built-in themes
- [Voice Input](/docs/voice-input) — Local speech-to-text configuration
- [Configuration](/docs/configuration) — Full config file reference