Themes

Craft Agent uses a 6-color theme system that lets you customize the visual appearance. You can override specific colors or install preset themes with complete visual styles.

Theme Hierarchy

Themes are applied in the following order of precedence:

Workspace override: Per-workspace theme in Settings → Appearance → Workspace Themes
App default: Selected in Settings → Appearance → Default Theme
Theme override file: ~/.craft-agent/theme.json - Override specific colors
Preset themes: ~/.craft-agent/themes/{name}.json - Complete theme packages

Workspaces without a custom theme inherit the app default.

Workspace Themes

Each workspace can have its own color theme that overrides the app default. This lets you visually distinguish between different projects or contexts.

Configuring Workspace Themes

Open Settings → Appearance
In the Default Theme section, set your app-wide default
In the Workspace Themes section, select a theme for each workspace:
- Use Default - Inherits the app default theme
- Custom theme - Select a specific preset

Storage Location

Workspace theme preferences are stored in the workspace config:

~/.craft-agent/workspaces/{id}/config.json

{
  "id": "ws_abc123",
  "name": "My Project",
  "defaults": {
    "colorTheme": "nord"
  }
}

When colorTheme is omitted or undefined, the workspace inherits the app default.

6-Color System

Color	Purpose	Usage
`background`	Surface/page background	Light/dark surface color
`foreground`	Text and icons	Primary text color
`accent`	Brand color, Execute mode	Highlights, active states, purple UI elements
`info`	Warnings, Ask mode	Amber indicators, attention states
`success`	Connected status	Green checkmarks, success states
`destructive`	Errors, delete actions	Red alerts, failed states

Theme Override File

Create ~/.craft-agent/theme.json to override specific colors:

{
  "accent": "oklch(0.58 0.22 293)",
  "dark": {
    "accent": "oklch(0.65 0.22 293)"
  }
}

All fields are optional. Only specify colors you want to override.

Dark Mode Support

The dark object provides optional overrides for dark mode. When the user’s system is in dark mode:

Base colors (top-level) are used as defaults
Any colors defined in dark override the base colors

This allows partial dark mode customization - only override what needs to differ.

Preset Themes

Preset themes are complete theme packages stored at ~/.craft-agent/themes/. Each preset is a JSON file with theme colors and metadata.

Preset Theme Schema

{
  "name": "Dracula",
  "description": "A dark theme with vibrant colors",
  "author": "Zeno Rocha",
  "license": "MIT",
  "source": "https://draculatheme.com",
  "supportedModes": ["dark"],

  "background": "oklch(0.22 0.02 280)",
  "foreground": "oklch(0.95 0.01 270)",
  "accent": "oklch(0.70 0.20 320)",
  "info": "oklch(0.78 0.14 70)",
  "success": "oklch(0.72 0.18 145)",
  "destructive": "oklch(0.65 0.22 28)",

  "shikiTheme": {
    "light": "github-light",
    "dark": "dracula"
  }
}

Preset Metadata Fields

Field	Description
`name`	Display name for the theme
`description`	Short description
`author`	Theme creator
`license`	License type (MIT, etc.)
`source`	URL to original theme
`supportedModes`	Array of `"light"`, `"dark"`, or both
`shikiTheme`	Syntax highlighting theme (light/dark variants)

Installing Preset Themes

Download or create a theme JSON file
Save it to ~/.craft-agent/themes/{name}.json
Select the theme in Settings → Appearance

Scenic Mode

Scenic mode displays a full-window background image with glass-style panels. This creates a visually immersive experience.

Enabling Scenic Mode

{
  "mode": "scenic",
  "backgroundImage": "mountains.jpg",

  "background": "oklch(0.15 0.02 270 / 0.8)",
  "paper": "oklch(0.18 0.02 270 / 0.6)",
  "navigator": "oklch(0.12 0.02 270 / 0.7)",
  "popoverSolid": "oklch(0.18 0.02 270)"
}

Scenic Mode Properties

Property	Description
`mode`	Set to `"scenic"` (default is `"solid"`)
`backgroundImage`	Image filename (relative to theme file) or URL

Surface Colors for Glass Panels

Scenic mode benefits from semi-transparent surface colors:

Color	Purpose
`paper`	AI messages, cards, elevated content
`navigator`	Left sidebar background
`input`	Input field background
`popover`	Dropdowns, modals, context menus
`popoverSolid`	Guaranteed 100% opaque popover background

Color Formats

Any valid CSS color format is supported:

Format	Example
Hex	`#8b5cf6`, `#8b5cf6cc` (with alpha)
RGB	`rgb(139, 92, 246)`, `rgba(139, 92, 246, 0.8)`
HSL	`hsl(262, 83%, 58%)`
OKLCH	`oklch(0.58 0.22 293)`
Named	`purple`, `rebeccapurple`

OKLCH Reference

OKLCH format: oklch(lightness chroma hue)

Component	Range	Description
Lightness	0-1	0 = black, 1 = white
Chroma	0-0.4	0 = gray, higher = more saturated
Hue	0-360	Color wheel angle

Common hues:

Red: ~25
Orange: ~70
Yellow: ~100
Green: ~145
Cyan: ~195
Blue: ~250
Purple: ~293
Pink: ~330

Examples

Minimal: Just change accent color

{
  "accent": "#3b82f6"
}

Custom brand colors

{
  "accent": "oklch(0.55 0.25 250)",
  "info": "oklch(0.70 0.15 200)",
  "dark": {
    "accent": "oklch(0.65 0.25 250)",
    "info": "oklch(0.75 0.12 200)"
  }
}

High contrast theme

{
  "background": "#ffffff",
  "foreground": "#000000",
  "dark": {
    "background": "#000000",
    "foreground": "#ffffff"
  }
}

Live Updates

Theme changes are applied immediately - no restart needed. Edit theme.json and the UI updates automatically.

Troubleshooting

Theme not applying

Verify JSON syntax is valid
Check file is in correct location (~/.craft-agent/theme.json for overrides, ~/.craft-agent/themes/ for presets)
Ensure color values are valid CSS colors

Colors look wrong in dark mode

Add explicit dark overrides
OKLCH colors may need higher lightness values for dark mode
Check if preset has supportedModes that excludes your current mode

Background image not showing

Ensure mode is set to "scenic"
Check image path is relative to theme file or a valid URL
Verify image file exists and is readable

Tips

Start with just accent

Changing only the accent color is the quickest way to personalize the app.

Use OKLCH for predictability

OKLCH colors behave more consistently across light/dark modes than hex or RGB.

Test in both modes

Always check your theme in both light and dark modes to ensure readability.

Keep contrast accessible

Ensure sufficient contrast between foreground and background colors.