feat: forward xterm theme background as COLORFGBG to spawned PTYs

Inject COLORFGBG (derived from the active xterm.js theme background
via Rec. 601 luma) into the env of every PTY the server spawns. This
gives Claude Code, Codex, and other TUIs a reliable light/dark signal
so they can match the page theme.

Windows ConPTY intercepts OSC 11 background-color queries and never
forwards xterm.js's response back to the child, leaving TUIs stuck on
their dark default. On a light coder-studio theme this surfaces as a
stark black bar behind user messages. COLORFGBG is the only signal
that survives the ConPTY layer.

- TerminalSpec gains an optional themeBackground hex string forwarded
  through session.create / terminal.create command schemas
- TerminalManager derives COLORFGBG once at spawn time and lets
  spec.env override when callers need to pin a specific value
- useTerminalThemeBackground hook reads the active theme atom and is
  threaded through every session/terminal create call site

Author: pallyoung

packages/server/src/commands/session.ts

@@ -42,6 +42,10 @@ registerCommand(
     workspaceId: z.string(),
     providerId: z.string(),
     draft: z.string().optional(),
+    themeBackground: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{3,8}$/)
+      .optional(),
   }),
   async (args, ctx) => {
     // Get workspace
@@ -75,6 +79,7 @@ registerCommand(
       providerId: args.providerId,
       provider,
       draft: args.draft,
+      themeBackground: args.themeBackground,
     });
   }
 );

packages/server/src/commands/terminal.ts

@@ -154,6 +154,10 @@ registerCommand(
     cols: z.number().int().positive().optional(),
     rows: z.number().int().positive().optional(),
     cwdPath: z.string().optional(),
+    themeBackground: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{3,8}$/)
+      .optional(),
   }),
   async (args, ctx) => {
     const workspace = ctx.workspaceMgr.get(args.workspaceId);
@@ -204,6 +208,7 @@ registerCommand(
       cwd,
       cols: args.cols ?? 120,
       rows: args.rows ?? 30,
+      themeBackground: args.themeBackground,
     });
 
     return terminal;

packages/server/src/session/manager.ts

@@ -31,6 +31,12 @@ export interface CreateSessionRequest {
   providerId: string;
   provider: ProviderDefinition;
   draft?: string;
+  /**
+   * Hex color of the xterm.js theme background that will render this
+   * session's terminal. Forwarded to TerminalSpec.themeBackground so the
+   * PTY env can advertise COLORFGBG to the agent CLI (see TerminalManager).
+   */
+  themeBackground?: string;
 }
 
 export interface SessionLogger {
@@ -249,6 +255,7 @@ export class SessionManager {
         CODER_STUDIO_SESSION_ID: sessionId,
       },
       title: req.provider.displayName,
+      themeBackground: req.themeBackground,
     };
 
     // Create terminal (delegates to TerminalManager)

packages/server/src/terminal/manager.test.ts

@@ -3,7 +3,7 @@
 import type { DomainEvent, Terminal } from "@coder-studio/core";
 import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";
 import { EventBus } from "../bus/event-bus";
-import { TerminalManager } from "./manager";
+import { computeColorFgBg, TerminalManager } from "./manager";
 import { RingBuffer } from "./ring-buffer";
 import * as snapshotBufferModule from "./terminal-snapshot-buffer";
 import type { PtyHost, PtyProcess, TerminalDatabase, TerminalSpec } from "./types";
@@ -164,6 +164,116 @@ describe("TerminalManager", () => {
       expect(spawnOptions.env.FORCE_COLOR).toBe("0");
     });
 
+    it("injects COLORFGBG=0;15 for a light themeBackground", () => {
+      const spec: TerminalSpec = {
+        workspaceId: "ws-123",
+        kind: "shell",
+        argv: ["bash"],
+        cwd: "/home/user",
+        themeBackground: "#fcfffd",
+      };
+
+      manager.create(spec);
+
+      const spawnOptions = (mockPtyHost.spawn as Mock).mock.calls[0][1];
+      expect(spawnOptions.env.COLORFGBG).toBe("0;15");
+    });
+
+    it("injects COLORFGBG=15;0 for a dark themeBackground", () => {
+      const spec: TerminalSpec = {
+        workspaceId: "ws-123",
+        kind: "shell",
+        argv: ["bash"],
+        cwd: "/home/user",
+        themeBackground: "#0b1218",
+      };
+
+      manager.create(spec);
+
+      const spawnOptions = (mockPtyHost.spawn as Mock).mock.calls[0][1];
+      expect(spawnOptions.env.COLORFGBG).toBe("15;0");
+    });
+
+    it("omits COLORFGBG when themeBackground is not provided", () => {
+      const spec: TerminalSpec = {
+        workspaceId: "ws-123",
+        kind: "shell",
+        argv: ["bash"],
+        cwd: "/home/user",
+      };
+
+      manager.create(spec);
+
+      const spawnOptions = (mockPtyHost.spawn as Mock).mock.calls[0][1];
+      expect(spawnOptions.env.COLORFGBG).toBeUndefined();
+    });
+
+    it("omits COLORFGBG when themeBackground is malformed", () => {
+      const spec: TerminalSpec = {
+        workspaceId: "ws-123",
+        kind: "shell",
+        argv: ["bash"],
+        cwd: "/home/user",
+        themeBackground: "not-a-color",
+      };
+
+      manager.create(spec);
+
+      const spawnOptions = (mockPtyHost.spawn as Mock).mock.calls[0][1];
+      expect(spawnOptions.env.COLORFGBG).toBeUndefined();
+    });
+
+    it("lets spec.env override the derived COLORFGBG when explicitly set", () => {
+      const spec: TerminalSpec = {
+        workspaceId: "ws-123",
+        kind: "shell",
+        argv: ["bash"],
+        cwd: "/home/user",
+        themeBackground: "#fcfffd",
+        env: {
+          COLORFGBG: "7;0",
+        },
+      };
+
+      manager.create(spec);
+
+      const spawnOptions = (mockPtyHost.spawn as Mock).mock.calls[0][1];
+      expect(spawnOptions.env.COLORFGBG).toBe("7;0");
+    });
+  });
+
+  describe("computeColorFgBg", () => {
+    it.each([
+      ["#ffffff", "0;15"],
+      ["#fcfffd", "0;15"],
+      ["#f5f7fa", "0;15"],
+      ["#fff", "0;15"],
+    ])("returns 0;15 (light bg) for %s", (input, expected) => {
+      expect(computeColorFgBg(input)).toBe(expected);
+    });
+
+    it.each([
+      ["#000000", "15;0"],
+      ["#0b1218", "15;0"],
+      ["#2e3440", "15;0"],
+      ["#000", "15;0"],
+    ])("returns 15;0 (dark bg) for %s", (input, expected) => {
+      expect(computeColorFgBg(input)).toBe(expected);
+    });
+
+    it("accepts #RRGGBBAA and ignores the alpha channel", () => {
+      expect(computeColorFgBg("#ffffff80")).toBe("0;15");
+      expect(computeColorFgBg("#00000080")).toBe("15;0");
+    });
+
+    it("returns undefined for malformed input", () => {
+      expect(computeColorFgBg("")).toBeUndefined();
+      expect(computeColorFgBg("white")).toBeUndefined();
+      expect(computeColorFgBg("#xyz")).toBeUndefined();
+      expect(computeColorFgBg("#12")).toBeUndefined();
+      expect(computeColorFgBg("rgb(0,0,0)")).toBeUndefined();
+    });
+
     it("should throw error on spawn failure", () => {
       const spawnError = new Error("Command not found");
       mockPtyHost.spawn = vi.fn().mockImplementation(() => {

packages/server/src/terminal/manager.ts

@@ -22,6 +22,59 @@ function isTerminalTraceEnabled(): boolean {
   return process.env.CODER_STUDIO_TERMINAL_TRACE === "1";
 }
 
+/**
+ * Parse a #RRGGBB / #RRGGBBAA / #RGB hex color into 8-bit RGB.
+ * Returns null for any unrecognized input so callers can skip injection.
+ */
+function parseHexColor(input: string): { r: number; g: number; b: number } | null {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("#")) {
+    return null;
+  }
+
+  const hex = trimmed.slice(1);
+  let r: number;
+  let g: number;
+  let b: number;
+  if (hex.length === 3) {
+    r = Number.parseInt(hex[0]! + hex[0]!, 16);
+    g = Number.parseInt(hex[1]! + hex[1]!, 16);
+    b = Number.parseInt(hex[2]! + hex[2]!, 16);
+  } else if (hex.length === 6 || hex.length === 8) {
+    r = Number.parseInt(hex.slice(0, 2), 16);
+    g = Number.parseInt(hex.slice(2, 4), 16);
+    b = Number.parseInt(hex.slice(4, 6), 16);
+  } else {
+    return null;
+  }
+
+  if ([r, g, b].some((v) => Number.isNaN(v))) {
+    return null;
+  }
+  return { r, g, b };
+}
+
+/**
+ * Derive an xterm-style COLORFGBG value from a theme background hex color.
+ *
+ * Returns "0;15" (dark text on light background) when the perceived luma is
+ * above the threshold, "15;0" (light text on dark background) otherwise.
+ * Returns undefined when the input cannot be parsed so the caller leaves the
+ * variable untouched and the child TUI falls back to its own default.
+ *
+ * Luma uses the Rec. 601 coefficients; the threshold is 0.5 which is the same
+ * cutoff most TUIs (Ink, chalk, bat, delta) use internally.
+ */
+export function computeColorFgBg(background: string): string | undefined {
+  const rgb = parseHexColor(background);
+  if (!rgb) {
+    return undefined;
+  }
+
+  const luma = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
+  return luma > 0.5 ? "0;15" : "15;0";
+}
+
 function countOccurrences(text: string, needle: string): number {
   return text.split(needle).length - 1;
 }
@@ -109,13 +162,24 @@ export class TerminalManager {
     // FORCE_COLOR makes agent CLIs that are spawned directly (e.g. Claude Code
     // via Ink/chalk, Codex) emit ANSI colors without relying on the user's
     // shell rc to set it. spec.env can still override explicitly.
+    //
+    // COLORFGBG advertises the frontend xterm theme's light/dark intent so
+    // TUIs that auto-pick color schemes (Claude Code, Codex, bat, delta, …)
+    // can match the page background. We derive it from spec.themeBackground.
+    // On Windows the ConPTY layer intercepts OSC 11 background-color queries
+    // and never forwards xterm.js's response back to the child, so this env
+    // variable is the only signal that survives the round trip.
+    const derivedColorFgBg = spec.themeBackground
+      ? computeColorFgBg(spec.themeBackground)
+      : undefined;
     const terminalEnv: Record<string, string> = {
       ...Object.fromEntries(
         Object.entries(process.env).filter((e): e is [string, string] => e[1] != null)
       ),
       TERM: "xterm-256color",
       COLORTERM: "truecolor",
       FORCE_COLOR: "3",
+      ...(derivedColorFgBg ? { COLORFGBG: derivedColorFgBg } : {}),
       ...spec.env,
     };
 

packages/server/src/terminal/types.ts

@@ -14,6 +14,15 @@ export interface TerminalSpec {
   cols?: number;
   rows?: number;
   title?: string;
+  /**
+   * Hex color (e.g. "#fcfffd") of the frontend xterm.js theme background that
+   * will render this terminal. The TerminalManager uses it to derive
+   * COLORFGBG so child TUIs (Claude Code, Codex, …) can pick a matching
+   * light/dark color scheme. This is the only signal that survives the
+   * Windows ConPTY layer, which otherwise intercepts OSC 11 background
+   * queries and forces TUIs into their dark fallback.
+   */
+  themeBackground?: string;
 }
 
 /**

packages/web/src/features/agent-panes/actions/use-provider-launcher.test.tsx

@@ -169,10 +169,14 @@ describe("useProviderLauncher", () => {
     await waitFor(() => {
       expect(dispatch).toHaveBeenCalledWith("provider.install.get", { jobId: "job-1" });
       expect(dispatch).toHaveBeenCalledWith("provider.runtimeStatus", {});
-      expect(dispatch).toHaveBeenCalledWith("session.create", {
-        workspaceId: "ws-1",
-        providerId: "claude",
-      });
+      expect(dispatch).toHaveBeenCalledWith(
+        "session.create",
+        expect.objectContaining({
+          workspaceId: "ws-1",
+          providerId: "claude",
+          themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+        })
+      );
     });
 
     expect(onSessionCreated).toHaveBeenCalledWith(
@@ -278,10 +282,14 @@ describe("useProviderLauncher", () => {
 
     await waitFor(() => {
       expect(dispatch).toHaveBeenCalledWith("provider.runtimeStatus", {});
-      expect(dispatch).toHaveBeenCalledWith("session.create", {
-        workspaceId: "ws-1",
-        providerId: "claude",
-      });
+      expect(dispatch).toHaveBeenCalledWith(
+        "session.create",
+        expect.objectContaining({
+          workspaceId: "ws-1",
+          providerId: "claude",
+          themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+        })
+      );
       expect(result.current.states.claude.runtime?.available).toBe(false);
       expect(result.current.states.claude.inlineError).toBe("Claude CLI is missing");
     });

packages/web/src/features/agent-panes/actions/use-provider-launcher.ts

@@ -7,6 +7,7 @@ import type {
 } from "@coder-studio/core";
 import { useEffect, useRef, useState } from "react";
 import type { DispatchCommand } from "../../../atoms/connection";
+import { useTerminalThemeBackground } from "../../../theme";
 
 export type ProviderId = "claude" | "codex";
 
@@ -65,6 +66,7 @@ export function useProviderLauncher(
 ): UseProviderLauncherResult {
   const [states, setStates] = useState<Record<ProviderId, ProviderCardState>>(buildStateMap());
   const pollingTimers = useRef<Partial<Record<ProviderId, number>>>({});
+  const themeBackground = useTerminalThemeBackground();
 
   useEffect(() => {
     let cancelled = false;
@@ -190,6 +192,7 @@ export function useProviderLauncher(
       const createResult = await dispatch<Session>("session.create", {
         workspaceId,
         providerId,
+        themeBackground,
       });
 
       if (createResult.ok && createResult.data) {
@@ -259,6 +262,7 @@ export function useProviderLauncher(
       const createResult = await dispatch<Session>("session.create", {
         workspaceId,
         providerId,
+        themeBackground,
       });
 
       if (createResult.ok && createResult.data) {
@@ -315,6 +319,7 @@ export function useProviderLauncher(
       const createResult = await dispatch<Session>("session.create", {
         workspaceId,
         providerId,
+        themeBackground,
       });
 
       if (createResult.ok && createResult.data) {

packages/web/src/features/agent-panes/components/session-card.test.tsx

@@ -163,10 +163,11 @@ describe("SessionCard", () => {
     await waitFor(() => {
       expect(sendCommand).toHaveBeenCalledWith(
         "session.create",
-        {
+        expect.objectContaining({
           workspaceId: "ws-123",
           providerId: "codex",
-        },
+          themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+        }),
         undefined
       );
     });

packages/web/src/features/agent-panes/index.test.tsx

@@ -760,10 +760,11 @@ describe("AgentPanes", () => {
     await waitFor(() => {
       expect(sendCommand).toHaveBeenCalledWith(
         "session.create",
-        {
+        expect.objectContaining({
           workspaceId: "ws-1",
           providerId: "claude",
-        },
+          themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+        }),
         undefined
       );
     });