feat: allow transparent background via config or flag

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable user-visible changes to Hunk are documented in this file.
 
 - Show the newly selected theme in the footer status bar when switching themes.
 - Added a Zenburn built-in theme (`theme = "zenburn"`), a warm low-contrast dark palette inspired by Jani Nurminen's original Zenburn. It also works as a custom-theme `base`.
+- Added a `--transparent-bg` flag and `transparent_background` config option for translucent terminal setups.
 
 ### Changed
 

README.md

@@ -127,9 +127,11 @@ exclude_untracked = false
 line_numbers = true
 wrap_lines = false
 agent_notes = false
+transparent_background = false
 ```
 
 `exclude_untracked` affects Git working-tree `hunk diff` sessions only.
+`transparent_background` can also be written as `transparentBackground`.
 
 Custom themes can inherit from any built-in base theme and override only the colors you care about:
 

src/core/cli.test.ts

@@ -83,6 +83,7 @@ describe("parseCli", () => {
       "--wrap",
       "--no-hunk-headers",
       "--agent-notes",
+      "--transparent-bg",
       "--watch",
     ]);
 
@@ -99,6 +100,25 @@ describe("parseCli", () => {
         wrapLines: true,
         hunkHeaders: false,
         agentNotes: true,
+        transparentBackground: true,
+      },
+    });
+  });
+
+  test("parses transparent background toggles", async () => {
+    const transparent = await parseCli(["bun", "hunk", "diff", "--transparent-bg"]);
+    const opaque = await parseCli(["bun", "hunk", "diff", "--no-transparent-bg"]);
+
+    expect(transparent).toMatchObject({
+      kind: "vcs",
+      options: {
+        transparentBackground: true,
+      },
+    });
+    expect(opaque).toMatchObject({
+      kind: "vcs",
+      options: {
+        transparentBackground: false,
       },
     });
   });

src/core/cli.ts

@@ -59,6 +59,7 @@ function buildCommonOptions(
     agentContext?: string;
     pager?: boolean;
     watch?: boolean;
+    transparentBackground?: boolean;
   },
   argv: string[],
 ): CommonOptions {
@@ -73,6 +74,7 @@ function buildCommonOptions(
     wrapLines: resolveBooleanFlag(argv, "--wrap", "--no-wrap"),
     hunkHeaders: resolveBooleanFlag(argv, "--hunk-headers", "--no-hunk-headers"),
     agentNotes: resolveBooleanFlag(argv, "--agent-notes", "--no-agent-notes"),
+    transparentBackground: resolveBooleanFlag(argv, "--transparent-bg", "--no-transparent-bg"),
   };
 }
 
@@ -90,7 +92,9 @@ function applyCommonOptions(command: Command) {
     .option("--hunk-headers", "show hunk metadata rows")
     .option("--no-hunk-headers", "hide hunk metadata rows")
     .option("--agent-notes", "show agent notes by default")
-    .option("--no-agent-notes", "hide agent notes by default");
+    .option("--no-agent-notes", "hide agent notes by default")
+    .option("--transparent-bg", "let terminal background show through Hunk surfaces")
+    .option("--no-transparent-bg", "paint Hunk surfaces with the active theme");
 }
 
 /** Attach auto-refresh support to review commands that can reopen their source input. */
@@ -152,6 +156,7 @@ function renderCliHelp() {
     "  --wrap / --no-wrap                      wrap or truncate long diff lines",
     "  --hunk-headers / --no-hunk-headers      show or hide hunk metadata rows",
     "  --agent-notes / --no-agent-notes        show or hide agent notes by default",
+    "  --transparent-bg / --no-transparent-bg  let terminal background show through Hunk surfaces",
     "  --theme <theme>                         named theme override",
     "",
     "Git diff options:",

src/core/config.test.ts

@@ -58,6 +58,7 @@ describe("config resolution", () => {
       [
         'theme = "graphite"',
         "line_numbers = false",
+        "transparentBackground = true",
         "",
         "[patch]",
         'mode = "split"',
@@ -87,6 +88,7 @@ describe("config resolution", () => {
       wrapLines: true,
       hunkHeaders: false,
       agentNotes: true,
+      transparentBackground: true,
     });
   });
 
@@ -215,6 +217,33 @@ describe("config resolution", () => {
     ).toThrow('Expected a [custom_theme] table when config selects theme = "custom".');
   });
 
+  test("accepts transparent background config and CLI overrides", () => {
+    const home = createTempDir("hunk-config-home-");
+    mkdirSync(join(home, ".config", "hunk"), { recursive: true });
+    writeFileSync(join(home, ".config", "hunk", "config.toml"), "transparent_background = true\n");
+
+    const cwd = createTempDir("hunk-config-cwd-");
+    const configured = resolveConfiguredCliInput(
+      {
+        kind: "vcs",
+        staged: false,
+        options: {},
+      },
+      { cwd, env: { HOME: home } },
+    );
+    const overridden = resolveConfiguredCliInput(
+      {
+        kind: "vcs",
+        staged: false,
+        options: { transparentBackground: false },
+      },
+      { cwd, env: { HOME: home } },
+    );
+
+    expect(configured.input.options.transparentBackground).toBe(true);
+    expect(overridden.input.options.transparentBackground).toBe(false);
+  });
+
   test("defaults unspecified themes to graphite, including piped pager-style patch input", () => {
     const home = createTempDir("hunk-config-home-");
     const cwd = createTempDir("hunk-config-cwd-");

src/core/config.ts

@@ -234,6 +234,9 @@ function readConfigPreferences(source: Record<string, unknown>): CommonOptions {
     hunkHeaders: normalizeBoolean(source.hunk_headers),
     agentNotes: normalizeBoolean(source.agent_notes),
     copyDecorations: normalizeBoolean(source.copy_decorations),
+    transparentBackground:
+      normalizeBoolean(source.transparentBackground) ??
+      normalizeBoolean(source.transparent_background),
   };
 }
 
@@ -253,6 +256,7 @@ function mergeOptions(base: CommonOptions, overrides: CommonOptions): CommonOpti
     hunkHeaders: overrides.hunkHeaders ?? base.hunkHeaders,
     agentNotes: overrides.agentNotes ?? base.agentNotes,
     copyDecorations: overrides.copyDecorations ?? base.copyDecorations,
+    transparentBackground: overrides.transparentBackground ?? base.transparentBackground,
   };
 }
 
@@ -317,6 +321,7 @@ export function resolveConfiguredCliInput(
     hunkHeaders: DEFAULT_VIEW_PREFERENCES.showHunkHeaders,
     agentNotes: DEFAULT_VIEW_PREFERENCES.showAgentNotes,
     copyDecorations: DEFAULT_VIEW_PREFERENCES.copyDecorations,
+    transparentBackground: false,
   };
 
   if (userConfigPath) {
@@ -345,6 +350,7 @@ export function resolveConfiguredCliInput(
     hunkHeaders: resolvedOptions.hunkHeaders ?? DEFAULT_VIEW_PREFERENCES.showHunkHeaders,
     agentNotes: resolvedOptions.agentNotes ?? DEFAULT_VIEW_PREFERENCES.showAgentNotes,
     copyDecorations: resolvedOptions.copyDecorations ?? DEFAULT_VIEW_PREFERENCES.copyDecorations,
+    transparentBackground: resolvedOptions.transparentBackground ?? false,
   };
 
   if (resolvedOptions.theme === "custom" && !resolvedCustomTheme) {

src/core/types.ts

@@ -84,6 +84,7 @@ export interface CommonOptions {
   hunkHeaders?: boolean;
   agentNotes?: boolean;
   copyDecorations?: boolean;
+  transparentBackground?: boolean;
 }
 
 export interface CustomSyntaxColorsConfig {

src/ui/App.tsx

@@ -28,7 +28,7 @@ import { fileRowId } from "./lib/ids";
 import { openSelectedFileInEditor } from "./lib/openInEditor";
 import { resolveResponsiveLayout } from "./lib/responsive";
 import { resizeSidebarWidth } from "./lib/sidebar";
-import { availableThemes, resolveTheme } from "./themes";
+import { availableThemes, resolveTheme, withTransparentBackground } from "./themes";
 
 type FocusArea = "files" | "filter" | "note";
 type ActiveAddNoteTarget = ActiveAddNoteAffordance & { fileId: string };
@@ -138,7 +138,14 @@ export function App({
     () => availableThemes(bootstrap.customTheme),
     [bootstrap.customTheme],
   );
-  const activeTheme = resolveTheme(themeId, detectedThemeMode ?? null, bootstrap.customTheme);
+  const baseTheme = resolveTheme(themeId, detectedThemeMode ?? null, bootstrap.customTheme);
+  const activeTheme = useMemo(
+    () =>
+      bootstrap.input.options.transparentBackground
+        ? withTransparentBackground(baseTheme)
+        : baseTheme,
+    [baseTheme, bootstrap.input.options.transparentBackground],
+  );
   const review = useReviewController({ files: bootstrap.changeset.files });
   const filteredFiles = review.visibleFiles;
   const selectedFile = review.selectedFile;

src/ui/diff/pierre.ts

@@ -240,7 +240,16 @@ function strengthenWordDiffBg(lineBg: string, signColor: string) {
 
 /** Resolve the inline word-diff background, strengthening theme colors that are too subtle to see. */
 function wordDiffHighlightBg(kind: SplitLineCell["kind"], theme: AppTheme) {
-  let cached = wordDiffBackgroundCache.get(theme.id);
+  const cacheKey = [
+    theme.id,
+    theme.addedBg,
+    theme.addedContentBg,
+    theme.removedBg,
+    theme.removedContentBg,
+    theme.contextContentBg,
+    theme.panelAlt,
+  ].join(":");
+  let cached = wordDiffBackgroundCache.get(cacheKey);
   if (!cached) {
     const addition =
       hexColorDistance(theme.addedContentBg, theme.addedBg) >= MIN_WORD_DIFF_BG_DISTANCE
@@ -257,7 +266,7 @@ function wordDiffHighlightBg(kind: SplitLineCell["kind"], theme: AppTheme) {
       deletion,
       empty: theme.panelAlt,
     };
-    wordDiffBackgroundCache.set(theme.id, cached);
+    wordDiffBackgroundCache.set(cacheKey, cached);
   }
 
   return cached[kind];

src/ui/themes.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { blendHex, hexColorDistance } from "./lib/color";
-import { CATPPUCCIN_PALETTES, resolveTheme } from "./themes";
+import {
+  CATPPUCCIN_PALETTES,
+  resolveTheme,
+  TRANSPARENT_BACKGROUND,
+  withTransparentBackground,
+} from "./themes";
 
 describe("themes", () => {
   test("resolves Catppuccin Latte and Mocha by theme id", () => {
@@ -107,4 +112,33 @@ describe("themes", () => {
       type: "#94bff3",
     });
   });
+
+  test("withTransparentBackground only swaps painted background fields", () => {
+    const theme = resolveTheme("graphite", null);
+    const transparent = withTransparentBackground(theme);
+
+    expect(transparent).toMatchObject({
+      background: TRANSPARENT_BACKGROUND,
+      panel: TRANSPARENT_BACKGROUND,
+      panelAlt: TRANSPARENT_BACKGROUND,
+      addedBg: TRANSPARENT_BACKGROUND,
+      removedBg: TRANSPARENT_BACKGROUND,
+      contextBg: TRANSPARENT_BACKGROUND,
+      addedContentBg: TRANSPARENT_BACKGROUND,
+      removedContentBg: TRANSPARENT_BACKGROUND,
+      contextContentBg: TRANSPARENT_BACKGROUND,
+      lineNumberBg: TRANSPARENT_BACKGROUND,
+      selectedHunk: TRANSPARENT_BACKGROUND,
+      noteBackground: TRANSPARENT_BACKGROUND,
+      noteTitleBackground: TRANSPARENT_BACKGROUND,
+    });
+    expect(transparent.id).toBe(theme.id);
+    expect(transparent.label).toBe(theme.label);
+    expect(transparent.text).toBe(theme.text);
+    expect(transparent.muted).toBe(theme.muted);
+    expect(transparent.addedSignColor).toBe(theme.addedSignColor);
+    expect(transparent.removedSignColor).toBe(theme.removedSignColor);
+    expect(transparent.syntaxColors).toBe(theme.syntaxColors);
+    expect(theme.background).not.toBe(TRANSPARENT_BACKGROUND);
+  });
 });

src/ui/themes.ts

@@ -12,6 +12,8 @@ import { ZENBURN_THEME } from "./themes/zenburn";
 export { CATPPUCCIN_PALETTES } from "./themes/catppuccin";
 export type { AppTheme, SyntaxColors, ThemeBase } from "./themes/types";
 
+export const TRANSPARENT_BACKGROUND = "transparent";
+
 export const THEMES: AppTheme[] = [
   GRAPHITE_THEME,
   MIDNIGHT_THEME,
@@ -112,3 +114,23 @@ export function resolveTheme(
 
   return fallbackTheme();
 }
+
+/** Return a copy of a theme whose painted surfaces allow the terminal background through. */
+export function withTransparentBackground(theme: AppTheme): AppTheme {
+  return {
+    ...theme,
+    background: TRANSPARENT_BACKGROUND,
+    panel: TRANSPARENT_BACKGROUND,
+    panelAlt: TRANSPARENT_BACKGROUND,
+    addedBg: TRANSPARENT_BACKGROUND,
+    removedBg: TRANSPARENT_BACKGROUND,
+    contextBg: TRANSPARENT_BACKGROUND,
+    addedContentBg: TRANSPARENT_BACKGROUND,
+    removedContentBg: TRANSPARENT_BACKGROUND,
+    contextContentBg: TRANSPARENT_BACKGROUND,
+    lineNumberBg: TRANSPARENT_BACKGROUND,
+    selectedHunk: TRANSPARENT_BACKGROUND,
+    noteBackground: TRANSPARENT_BACKGROUND,
+    noteTitleBackground: TRANSPARENT_BACKGROUND,
+  };
+}