Skip to main content
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:
  1. Workspace override: Per-workspace theme in Settings → Appearance → Workspace Themes
  2. App default: Selected in Settings → Appearance → Default Theme
  3. Theme override file: ~/.craft-agent/theme.json - Override specific colors
  4. 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

  1. Open Settings → Appearance
  2. In the Default Theme section, set your app-wide default
  3. In the Workspace Themes section, select a theme for each workspace:
    • Use Default - Inherits the app default theme
    • Custom theme - Select a specific preset
Theme changes apply immediately across all windows. If you have multiple windows open with the same workspace, they all update in real-time.

​
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.
This is the workspace-specific default theme. It overrides the app default for new and existing sessions in that workspace.

​
6-Color System

ColorPurposeUsage
backgroundSurface/page backgroundLight/dark surface color
foregroundText and iconsPrimary text color
accentBrand color, Execute modeHighlights, active states, purple UI elements
infoWarnings, Ask modeAmber indicators, attention states
successConnected statusGreen checkmarks, success states
destructiveErrors, delete actionsRed 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:
  1. Base colors (top-level) are used as defaults
  2. 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

FieldDescription
nameDisplay name for the theme
descriptionShort description
authorTheme creator
licenseLicense type (MIT, etc.)
sourceURL to original theme
supportedModesArray of "light", "dark", or both
shikiThemeSyntax highlighting theme (light/dark variants)

​
Installing Preset Themes

  1. Download or create a theme JSON file
  2. Save it to ~/.craft-agent/themes/{name}.json
  3. 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

PropertyDescription
modeSet to "scenic" (default is "solid")
backgroundImageImage filename (relative to theme file) or URL

​
Surface Colors for Glass Panels

Scenic mode benefits from semi-transparent surface colors:
ColorPurpose
paperAI messages, cards, elevated content
navigatorLeft sidebar background
inputInput field background
popoverDropdowns, modals, context menus
popoverSolidGuaranteed 100% opaque popover background
Scenic themes automatically force dark mode for better contrast with background images.

​
Color Formats

Any valid CSS color format is supported:
FormatExample
Hex#8b5cf6, #8b5cf6cc (with alpha)
RGBrgb(139, 92, 246), rgba(139, 92, 246, 0.8)
HSLhsl(262, 83%, 58%)
OKLCHoklch(0.58 0.22 293)
Namedpurple, rebeccapurple
Recommendation: Use OKLCH for perceptually uniform colors that look consistent across light and dark modes.

​
OKLCH Reference

OKLCH format: oklch(lightness chroma hue)
ComponentRangeDescription
Lightness0-10 = black, 1 = white
Chroma0-0.40 = gray, higher = more saturated
Hue0-360Color 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

  • 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
  • Add explicit dark overrides
  • OKLCH colors may need higher lightness values for dark mode
  • Check if preset has supportedModes that excludes your current mode
  • 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

Changing only the accent color is the quickest way to personalize the app.
OKLCH colors behave more consistently across light/dark modes than hex or RGB.
Always check your theme in both light and dark modes to ensure readability.
Ensure sufficient contrast between foreground and background colors.