feat(ui): add new theme "auto" that automatically switches between da…

CHANGELOG.md

@@ -6,10 +6,15 @@ All notable user-visible changes to Hunk are documented in this file.
 
 ### Added
 
+- Added automatic switching between dark and light mode themes based on system preferences.
+- Added a "Follow system" option to the theme menu.
+
 ### Changed
 
 ### Fixed
 
+- Improved theme-mode detection for pager and patch flows by falling back to system preferences when stdin is redirected.
+
 ## [0.10.0] - 2026-04-21
 
 ### Added

README.md

@@ -110,7 +110,9 @@ You can persist preferences to a config file:
 Example:
 
 ```toml
-theme = "graphite"   # graphite, midnight, paper, ember
+theme = "graphite"   # graphite, midnight, paper, ember, auto (based on system pref.)
+theme_light = "paper" # default light theme for auto theme
+theme_dark = "graphite" # default dark theme for auto theme
 mode = "auto"        # auto, split, stack
 exclude_untracked = false
 line_numbers = true

docs/opentui-component.md

@@ -99,19 +99,19 @@ if (!metadata) {
 
 ## Props
 
-| Prop                | Type                                             | Default      | Notes                                                                     |
-| ------------------- | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------- |
-| `diff`              | `HunkDiffFile`                                   | `undefined`  | File to render. When omitted, the component shows an empty-state message. |
-| `layout`            | `"split" \| "stack"`                             | `"split"`    | Chooses side-by-side or stacked rendering.                                |
-| `width`             | `number`                                         | —            | Required content width in terminal columns.                               |
-| `theme`             | `"graphite" \| "midnight" \| "paper" \| "ember"` | `"graphite"` | Matches Hunk's built-in themes.                                           |
-| `showLineNumbers`   | `boolean`                                        | `true`       | Toggles line-number columns.                                              |
-| `showHunkHeaders`   | `boolean`                                        | `true`       | Toggles `@@ ... @@` hunk header rows.                                     |
-| `wrapLines`         | `boolean`                                        | `false`      | Wraps long lines instead of clipping horizontally.                        |
-| `horizontalOffset`  | `number`                                         | `0`          | Scroll offset for non-wrapped code rows.                                  |
-| `highlight`         | `boolean`                                        | `true`       | Enables syntax highlighting.                                              |
-| `scrollable`        | `boolean`                                        | `true`       | Set to `false` if your parent view owns scrolling.                        |
-| `selectedHunkIndex` | `number`                                         | `0`          | Highlights one hunk as the active target.                                 |
+| Prop                | Type                                                       | Default      | Notes                                                                     |
+| ------------------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------- |
+| `diff`              | `HunkDiffFile`                                             | `undefined`  | File to render. When omitted, the component shows an empty-state message. |
+| `layout`            | `"split" \| "stack"`                                       | `"split"`    | Chooses side-by-side or stacked rendering.                                |
+| `width`             | `number`                                                   | —            | Required content width in terminal columns.                               |
+| `theme`             | `"auto" \| "graphite" \| "midnight" \| "paper" \| "ember"` | `"graphite"` | Matches Hunk's built-in themes.                                           |
+| `showLineNumbers`   | `boolean`                                                  | `true`       | Toggles line-number columns.                                              |
+| `showHunkHeaders`   | `boolean`                                                  | `true`       | Toggles `@@ ... @@` hunk header rows.                                     |
+| `wrapLines`         | `boolean`                                                  | `false`      | Wraps long lines instead of clipping horizontally.                        |
+| `horizontalOffset`  | `number`                                                   | `0`          | Scroll offset for non-wrapped code rows.                                  |
+| `highlight`         | `boolean`                                                  | `true`       | Enables syntax highlighting.                                              |
+| `scrollable`        | `boolean`                                                  | `true`       | Set to `false` if your parent view owns scrolling.                        |
+| `selectedHunkIndex` | `number`                                                   | `0`          | Highlights one hunk as the active target.                                 |
 
 ## Other exports
 

src/core/config.test.ts

@@ -99,6 +99,23 @@ describe("config resolution", () => {
     expect(resolved.input.options.theme).toBe("graphite");
   });
 
+  test("resolves custom light and dark theme preferences", () => {
+    const home = createTempDir("hunk-config-home-");
+    mkdirSync(join(home, ".config", "hunk"), { recursive: true });
+    writeFileSync(
+      join(home, ".config", "hunk", "config.toml"),
+      ['theme_light = "ember"', 'theme_dark = "midnight"'].join("\n"),
+    );
+
+    const resolved = resolveConfiguredCliInput(createPatchPagerInput(), {
+      cwd: createTempDir("hunk-config-cwd-"),
+      env: { HOME: home },
+    });
+
+    expect(resolved.input.options.themeLight).toBe("ember");
+    expect(resolved.input.options.themeDark).toBe("midnight");
+  });
+
   test("command-specific config sections also apply to show mode", () => {
     const home = createTempDir("hunk-config-home-");
     mkdirSync(join(home, ".config", "hunk"), { recursive: true });

src/core/config.ts

@@ -5,6 +5,8 @@ import type { CliInput, CommonOptions, LayoutMode, PersistedViewPreferences } fr
 
 const DEFAULT_VIEW_PREFERENCES: PersistedViewPreferences = {
   mode: "auto",
+  themeLight: "paper",
+  themeDark: "graphite",
   showLineNumbers: true,
   wrapLines: false,
   showHunkHeaders: true,
@@ -46,6 +48,8 @@ function readConfigPreferences(source: Record<string, unknown>): CommonOptions {
   return {
     mode: normalizeLayoutMode(source.mode),
     theme: normalizeString(source.theme),
+    themeLight: normalizeString(source.theme_light),
+    themeDark: normalizeString(source.theme_dark),
     excludeUntracked: normalizeBoolean(source.exclude_untracked),
     lineNumbers: normalizeBoolean(source.line_numbers),
     wrapLines: normalizeBoolean(source.wrap_lines),
@@ -60,6 +64,8 @@ function mergeOptions(base: CommonOptions, overrides: CommonOptions): CommonOpti
     ...base,
     mode: overrides.mode ?? base.mode,
     theme: overrides.theme ?? base.theme,
+    themeLight: overrides.themeLight ?? base.themeLight,
+    themeDark: overrides.themeDark ?? base.themeDark,
     agentContext: overrides.agentContext ?? base.agentContext,
     pager: overrides.pager ?? base.pager,
     watch: overrides.watch ?? base.watch,
@@ -134,6 +140,8 @@ export function resolveConfiguredCliInput(
     // Keep the built-in theme default explicit so stdin-backed startup paths do not depend on
     // renderer theme-mode detection for their initial palette.
     theme: "graphite",
+    themeLight: DEFAULT_VIEW_PREFERENCES.themeLight,
+    themeDark: DEFAULT_VIEW_PREFERENCES.themeDark,
     agentContext: input.options.agentContext,
     pager: input.options.pager ?? false,
     watch: input.options.watch ?? false,
@@ -166,6 +174,8 @@ export function resolveConfiguredCliInput(
     watch: input.options.watch ?? false,
     excludeUntracked: resolvedOptions.excludeUntracked ?? false,
     mode: resolvedOptions.mode ?? DEFAULT_VIEW_PREFERENCES.mode,
+    themeLight: resolvedOptions.themeLight ?? DEFAULT_VIEW_PREFERENCES.themeLight,
+    themeDark: resolvedOptions.themeDark ?? DEFAULT_VIEW_PREFERENCES.themeDark,
     lineNumbers: resolvedOptions.lineNumbers ?? DEFAULT_VIEW_PREFERENCES.showLineNumbers,
     wrapLines: resolvedOptions.wrapLines ?? DEFAULT_VIEW_PREFERENCES.wrapLines,
     hunkHeaders: resolvedOptions.hunkHeaders ?? DEFAULT_VIEW_PREFERENCES.showHunkHeaders,

src/core/loaders.ts

@@ -32,6 +32,7 @@ import type {
   ShowCommandInput,
   StashShowCommandInput,
 } from "./types";
+import { detectSystemThemeMode, usesPipedPatchInput } from "./terminal";
 
 interface LoadAppBootstrapOptions {
   cwd?: string;
@@ -585,6 +586,9 @@ export async function loadAppBootstrap(
     changeset,
     initialMode: input.options.mode ?? "auto",
     initialTheme: input.options.theme,
+    initialThemeLight: input.options.themeLight,
+    initialThemeDark: input.options.themeDark,
+    initialThemeMode: usesPipedPatchInput(input) ? detectSystemThemeMode() : undefined,
     initialShowLineNumbers: input.options.lineNumbers ?? true,
     initialWrapLines: input.options.wrapLines ?? false,
     initialShowHunkHeaders: input.options.hunkHeaders ?? true,

src/core/terminal.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { CliInput } from "./types";
 import {
+  detectSystemThemeMode,
   openControllingTerminal,
   resolveRuntimeCliInput,
   shouldUseMouseForApp,
@@ -114,3 +115,45 @@ describe("controlling terminal attachment", () => {
     expect(controllingTerminal).toBeNull();
   });
 });
+
+describe("system theme detection", () => {
+  const isDarwin = process.platform === "darwin";
+
+  test("detects dark mode on macOS", () => {
+    if (!isDarwin) return;
+
+    const spawnSync = ((args: string[]) => {
+      expect(args).toEqual(["defaults", "read", "-g", "AppleInterfaceStyle"]);
+      return { stdout: Buffer.from("Dark\n") };
+    }) as typeof Bun.spawnSync;
+
+    expect(detectSystemThemeMode({ spawnSync })).toBe("dark");
+  });
+
+  test("detects light mode on macOS", () => {
+    if (!isDarwin) return;
+
+    const spawnSync = ((args: string[]) => {
+      expect(args).toEqual(["defaults", "read", "-g", "AppleInterfaceStyle"]);
+      return { stdout: Buffer.from("\n") };
+    }) as typeof Bun.spawnSync;
+
+    expect(detectSystemThemeMode({ spawnSync })).toBe("light");
+  });
+
+  test("falls back to light mode on macOS when the command fails", () => {
+    if (!isDarwin) return;
+
+    const spawnSync = (() => {
+      throw new Error("Command failed");
+    }) as typeof Bun.spawnSync;
+
+    expect(detectSystemThemeMode({ spawnSync })).toBe("light");
+  });
+
+  test("returns undefined on non-macOS platforms", () => {
+    if (isDarwin) return;
+
+    expect(detectSystemThemeMode()).toBeUndefined();
+  });
+});

src/core/terminal.ts

@@ -39,6 +39,26 @@ export function shouldUseMouseForApp({
   return stdinIsTTY || hasControllingTerminal;
 }
 
+/** Detect the system theme mode as a fallback when terminal-based detection is unavailable. */
+export function detectSystemThemeMode(
+  deps: { spawnSync: typeof Bun.spawnSync } = { spawnSync: Bun.spawnSync },
+): "light" | "dark" | undefined {
+  if (process.platform !== "darwin") {
+    return undefined;
+  }
+
+  try {
+    // defaults read -g AppleInterfaceStyle returns "Dark" in dark mode.
+    // It exits with code 1 if the key doesn't exist (which means light mode).
+    const proc = deps.spawnSync(["defaults", "read", "-g", "AppleInterfaceStyle"]);
+    const output = proc.stdout.toString().trim();
+    return output === "Dark" ? "dark" : "light";
+  } catch {
+    // On macOS, if the key is missing, it's light mode.
+    return "light";
+  }
+}
+
 export interface ControllingTerminal {
   stdin: tty.ReadStream;
   close: () => void;

src/core/types.ts

@@ -55,6 +55,8 @@ export interface Changeset {
 export interface CommonOptions {
   mode?: LayoutMode;
   theme?: string;
+  themeLight?: string;
+  themeDark?: string;
   agentContext?: string;
   pager?: boolean;
   watch?: boolean;
@@ -68,6 +70,8 @@ export interface CommonOptions {
 export interface PersistedViewPreferences {
   mode: LayoutMode;
   theme?: string;
+  themeLight?: string;
+  themeDark?: string;
   showLineNumbers: boolean;
   wrapLines: boolean;
   showHunkHeaders: boolean;
@@ -271,6 +275,9 @@ export interface AppBootstrap {
   changeset: Changeset;
   initialMode: LayoutMode;
   initialTheme?: string;
+  initialThemeLight?: string;
+  initialThemeDark?: string;
+  initialThemeMode?: "light" | "dark";
   initialShowLineNumbers?: boolean;
   initialWrapLines?: boolean;
   initialShowHunkHeaders?: boolean;

src/opentui/HunkDiffView.test.tsx

@@ -61,6 +61,6 @@ describe("HunkDiffView", () => {
   });
 
   test("exports the documented built-in theme names", () => {
-    expect(HUNK_DIFF_THEME_NAMES).toEqual(["graphite", "midnight", "paper", "ember"]);
+    expect(HUNK_DIFF_THEME_NAMES).toEqual(["auto", "graphite", "midnight", "paper", "ember"]);
   });
 });

src/opentui/themes.ts

@@ -1,3 +1,3 @@
-export const HUNK_DIFF_THEME_NAMES = ["graphite", "midnight", "paper", "ember"] as const;
+export const HUNK_DIFF_THEME_NAMES = ["auto", "graphite", "midnight", "paper", "ember"] as const;
 
 export type HunkDiffThemeName = (typeof HUNK_DIFF_THEME_NAMES)[number];

src/ui/App.tsx

@@ -2,6 +2,7 @@ import {
   MouseButton,
   type MouseEvent as TuiMouseEvent,
   type ScrollBoxRenderable,
+  type ThemeMode,
 } from "@opentui/core";
 import { useRenderer, useTerminalDimensions } from "@opentui/react";
 import { Suspense, lazy, useCallback, useEffect, useMemo, useState, useRef } from "react";
@@ -50,6 +51,8 @@ function withCurrentViewOptions(
   view: {
     layoutMode: LayoutMode;
     themeId: string;
+    themeLight: string;
+    themeDark: string;
     showAgentNotes: boolean;
     showHunkHeaders: boolean;
     showLineNumbers: boolean;
@@ -62,6 +65,8 @@ function withCurrentViewOptions(
       ...input.options,
       mode: view.layoutMode,
       theme: view.themeId,
+      themeLight: view.themeLight,
+      themeDark: view.themeDark,
       agentNotes: view.showAgentNotes,
       hunkHeaders: view.showHunkHeaders,
       lineNumbers: view.showLineNumbers,
@@ -101,8 +106,11 @@ export function App({
   const layoutToggleScrollTopRef = useRef<number | null>(null);
   const [layoutToggleRequestId, setLayoutToggleRequestId] = useState(0);
   const [layoutMode, setLayoutMode] = useState<LayoutMode>(bootstrap.initialMode);
-  const [themeId, setThemeId] = useState(
-    () => resolveTheme(bootstrap.initialTheme, renderer.themeMode).id,
+  const [themeId, setThemeId] = useState(bootstrap.initialTheme ?? "auto");
+  const [themeLight, _setThemeLight] = useState(bootstrap.initialThemeLight ?? "paper");
+  const [themeDark, _setThemeDark] = useState(bootstrap.initialThemeDark ?? "graphite");
+  const [systemThemeMode, setSystemThemeMode] = useState(
+    bootstrap.initialThemeMode ?? renderer.themeMode,
   );
   const [showAgentNotes, setShowAgentNotes] = useState(bootstrap.initialShowAgentNotes ?? false);
   const [showLineNumbers, setShowLineNumbers] = useState(bootstrap.initialShowLineNumbers ?? true);
@@ -118,7 +126,17 @@ export function App({
   const [resizeStartWidth, setResizeStartWidth] = useState<number | null>(null);
 
   const pagerMode = Boolean(bootstrap.input.options.pager);
-  const activeTheme = resolveTheme(themeId, renderer.themeMode);
+  const activeTheme = resolveTheme(themeId, systemThemeMode, themeLight, themeDark);
+
+  useEffect(() => {
+    const handleThemeMode = (mode: ThemeMode) => {
+      setSystemThemeMode(mode);
+    };
+    renderer.on("theme_mode", handleThemeMode);
+    return () => {
+      renderer.off("theme_mode", handleThemeMode);
+    };
+  }, [renderer]);
   const review = useReviewController({ files: bootstrap.changeset.files });
   const filteredFiles = review.visibleFiles;
   const selectedFile = review.selectedFile;
@@ -346,6 +364,8 @@ export function App({
     const nextInput = withCurrentViewOptions(bootstrap.input, {
       layoutMode,
       themeId,
+      themeLight,
+      themeDark,
       showAgentNotes,
       showHunkHeaders,
       showLineNumbers,
@@ -471,6 +491,7 @@ export function App({
   const menus = useMemo(
     () =>
       buildAppMenus({
+        themeId,
         activeThemeId: activeTheme.id,
         canRefreshCurrentInput,
         focusFilter,
@@ -497,6 +518,7 @@ export function App({
         wrapLines,
       }),
     [
+      themeId,
       activeTheme.id,
       canRefreshCurrentInput,
       focusFilter,

src/ui/lib/appMenus.ts

@@ -3,6 +3,7 @@ import type { MenuEntry, MenuId } from "../components/chrome/menu";
 import { THEMES } from "../themes";
 
 export interface BuildAppMenusOptions {
+  themeId: string;
   activeThemeId: string;
   canRefreshCurrentInput: boolean;
   focusFilter: () => void;
@@ -31,6 +32,7 @@ export interface BuildAppMenusOptions {
 
 /** Build the top-level app menus from the current app state and actions. */
 export function buildAppMenus({
+  themeId,
   activeThemeId,
   canRefreshCurrentInput,
   focusFilter,
@@ -56,12 +58,21 @@ export function buildAppMenus({
   toggleSidebar,
   wrapLines,
 }: BuildAppMenusOptions): Record<MenuId, MenuEntry[]> {
-  const themeMenuEntries: MenuEntry[] = THEMES.map((theme) => ({
-    kind: "item",
-    label: theme.label,
-    checked: theme.id === activeThemeId,
-    action: () => selectThemeId(theme.id),
-  }));
+  const themeMenuEntries: MenuEntry[] = [
+    {
+      kind: "item",
+      label: "Follow system",
+      checked: themeId === "auto",
+      action: () => selectThemeId(themeId === "auto" ? activeThemeId : "auto"),
+    },
+    { kind: "separator" },
+    ...THEMES.map((theme) => ({
+      kind: "item" as const,
+      label: theme.label,
+      checked: theme.id === themeId || (themeId === "auto" && theme.id === activeThemeId),
+      action: () => selectThemeId(theme.id),
+    })),
+  ];
 
   const fileMenuEntries: MenuEntry[] = [
     {