Add colors.theme setting to override auto-detected dark/light mode for terminal background colors

[joelpt]

Diagnostic Information

Property	Value
CLI Version	0.13.4
Node.js Version	v24.10.0
OS	darwin
OS Version	25.3.0
Architecture	arm64
Capabilities	web
Claude CLI Version	2.1.86 (Claude Code)

Feature Request

Current Behavior

detectDarkMode() in src/utils/env.ts reads defaults read -g AppleInterfaceStyle to determine whether to use the light or dark color palette for terminal background colors. There is no way to override this via settings.

Desired Behavior

Add a colors.theme setting that accepts "dark", "light", or "auto" (default). This would allow users to force a specific color palette regardless of their macOS system appearance.

Example settings.json:

{
  "colors": {
    "terminal": true,
    "theme": "dark"
  }
}

Motivation

• Users with dark terminal backgrounds running macOS in light mode get light/pastel terminal colors that clash with their terminal theme
• Users may want consistent iloom colors regardless of system appearance changes
• The dark palette (deep blues, greens, violets) works better for dark terminals even when macOS is in light mode
• Currently the only workaround is disabling terminal colors entirely (colors.terminal: false)

Suggested Implementation

1. Add theme to the colors schema in settings: z.enum(["auto", "dark", "light"]).default("auto")
2. In detectDarkMode() (or its callers), check settings.colors.theme first — if not "auto", return that value directly instead of querying macOS
3. Settings hierarchy already supports global/project/local, so users can set this globally or per-project

---

Enhancement Request Analysis

Questions for Reporter

Question	Answer
How do you envision the theme override working when iloom is launched? Should the setting be checked on every loom creation, or cached for performance?	@joelpt, to reply, please edit this issue to answer these questions.
Would you prefer the override to only affect terminal colors, or should it also influence the VSCode color themes (when colors.vscode is enabled)?
If a user sets colors.theme: "dark" but their terminal is actually light-themed, should iloom display a warning about the potential color mismatch?
Should the logger's colored output also respect this theme override, or remain tied to the actual system appearance for readability?

Problem Summary
Users cannot override the automatic dark/light mode detection for terminal colors. The system automatically reads macOS appearance settings to determine color palettes, but this doesn't align with all terminal configurations—particularly when users run dark-themed terminals on light-mode macOS systems. The resulting color clash makes workspace identification difficult and impacts the visual experience.

User Impact
This affects macOS users who prefer terminal themes that don't match their system appearance setting. It particularly impacts developers who:

• Use dark terminal themes exclusively for better code readability
• Work in mixed environments where system appearance changes throughout the day
• Share configurations across machines with different appearance preferences
• Use terminal emulators with custom themes independent of system settings

Enhancement Goal
Enable users to manually specify their preferred color theme (dark/light) independent of system appearance detection, while maintaining the current auto-detection as the default behavior. This provides flexibility without breaking existing workflows.

Next Steps

• Reporter to answer questions above for full context
• Determine if theme override should affect all color contexts or just terminal colors
• Consider adding validation to warn about potential terminal/theme mismatches

---

📋 Complete Context & Details (click to expand)

Current Behavior
The detectDarkMode() function in src/utils/terminal.ts:43 currently determines the color theme by:

1. Checking if the platform is macOS (returns 'light' for non-macOS)
2. Reading the system appearance via defaults read -g AppleInterfaceStyle
3. Returning 'dark' if the value is "Dark", otherwise 'light'

This theme selection affects:

• Terminal background colors via LoomManager.ts:356 and LoomManager.ts:1352
• Color palette selection in selectDistinctColor() and generateColorFromBranchName()
• Logger emoji and color choices in src/utils/logger.ts:38

Proposed Solution

1. Schema Update (src/lib/SettingsManager.ts:717-733):

   • Add theme: z.enum(['auto', 'dark', 'light']).default('auto').describe('Color theme override for terminal colors. "auto" uses system appearance detection.')
   • Place within the existing colors object alongside terminal and vscode settings

2. Detection Logic Enhancement (src/utils/terminal.ts):

   • Create a new function getThemeMode(settings?: { colors?: { theme?: string } }): Promise<ThemeMode>
   • Check settings first: if theme !== 'auto', return the specified theme immediately
   • Otherwise, fall back to existing detectDarkMode() logic

3. Integration Points:

   • Update LoomManager.ts to pass settings to theme detection (lines 356, 1352)
   • Ensure logger initialization respects the theme override
   • Maintain backward compatibility by defaulting to 'auto'

Benefits

• Users gain full control over their color experience
• No more color clashes between system appearance and terminal themes
• Consistent workspace colors across different machines and environments
• Preserves existing auto-detection for users who prefer system integration
• Follows iloom's existing settings hierarchy (global → project → local)