pi-system-theme-ssh-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mise42
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# pi-system-theme-ssh-bridge
+
+Sync pi theme with system appearance — works both **locally** and **over SSH**.
+
+Drop-in replacement for `pi-system-theme`, with added SSH support.
+
+## How it works
+
+The extension uses a three-layer detection strategy (in priority order):
+
+| Priority | Strategy | When it helps |
+|----------|----------|---------------|
+| 1 | **Override file** (`~/.pi/agent/system-theme-override.json`) | Manual push from another machine |
+| 2 | **Terminal query** (OSC 11 background-color) | SSH sessions — escape sequences travel through the SSH tunnel back to your local Ghostty, which responds with its current background color |
+| 3 | **OS-level detection** (macOS `defaults` / GNOME `gsettings` / Windows `reg`) | Local sessions without a capable terminal |
+
+### Why it works over SSH
+
+When you SSH into a remote machine, your local terminal (Ghostty) is still rendering everything. The extension sends an [OSC 11](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) query (`\033]11;?\033\\`) to stdout. This travels through the SSH tunnel to Ghostty, which replies with the current background RGB. The extension parses the luminance to determine dark or light.
+
+This means: **when Ghostty switches `theme = auto` on your Laptop, the remote pi detects it within seconds — no push scripts needed.**
+
+The OSC 11 query runs in a short-lived subprocess that opens `/dev/tty` directly, so it doesn't interfere with pi's own terminal I/O.
+
+## Install
+
+```bash
+pi install npm:pi-system-theme-ssh-bridge
+```
+
+> **Important:** Remove `pi-system-theme` first to avoid two extensions fighting over `setTheme`:
+> ```bash
+> pi remove npm:pi-system-theme
+> ```
+
+## Configuration
+
+Use the `/system-theme` command inside pi to configure:
+
+1. **Dark theme** name (default: `dark`)
+2. **Light theme** name (default: `light`)
+3. **Poll interval** in ms (default: `2000`)
+
+Settings are saved to `~/.pi/agent/system-theme.json` (same location as `pi-system-theme`, so existing config carries over).
+
+## Override file (optional)
+
+For environments where neither OSC 11 nor OS detection works, you can push an override file manually:
+
+```bash
+# On your Laptop, push current appearance to Desktop:
+./push-theme-override.sh user@desktop
+
+# Or inside pi on any machine:
+/system-theme-push dark
+/system-theme-push light
+/system-theme-push auto    # clears override, falls back to detection
+```
+
+### Override file format
+
+```json
+{
+  "appearance": "dark",
+  "updatedAt": "2026-02-22T07:00:00Z",
+  "source": "my-laptop"
+}
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PI_SYSTEM_THEME_OVERRIDE_FILE` | `~/.pi/agent/system-theme-override.json` | Override file path |
+| `PI_SYSTEM_THEME_OVERRIDE_MAX_AGE_MS` | `60000` | Max age before override is considered stale |
+
+## Compatibility
+
+- **Terminals:** Any terminal supporting OSC 11 color queries (Ghostty, iTerm2, kitty, foot, WezTerm, xterm, etc.)
+- **OS detection:** macOS, Linux (GNOME gsettings), Windows
+- **SSH:** Works transparently — no special setup required
+- **Ghostty `theme = auto`:** Fully supported. When Ghostty switches colors, the next poll detects it.
+
+## Migrating from pi-system-theme
+
+1. `pi remove npm:pi-system-theme`
+2. `pi install npm:pi-system-theme-ssh-bridge`
+3. Done. Your `~/.pi/agent/system-theme.json` config (if any) is reused automatically.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,588 @@
+/**
+ * pi-system-theme-ssh-bridge
+ *
+ * Sync pi theme with system appearance — works both locally and over SSH.
+ *
+ * Detection strategy (in priority order):
+ *   1. Override file  (~/.pi/agent/system-theme-override.json)
+ *      – If present & fresh, use its "dark" / "light" value directly.
+ *      – If value is "auto", fall through.
+ *   2. Terminal query  (OSC 11 background-color)
+ *      – Works transparently over SSH because escape sequences travel
+ *        through the SSH tunnel back to the local terminal (Ghostty, etc.).
+ *      – A helper subprocess opens /dev/tty to avoid interfering with
+ *        pi's own stdin/stdout.
+ *   3. OS-level detection  (macOS defaults / GNOME gsettings / Windows reg)
+ *      – Classic local detection, same as pi-system-theme.
+ */
+
+import { execFile, spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Appearance = "dark" | "light";
+type OverrideAppearance = Appearance | "auto";
+
+type Config = {
+    darkTheme: string;
+    lightTheme: string;
+    pollMs: number;
+    overrideFile: string;
+    overrideMaxAgeMs: number;
+};
+
+type OverridePayload = {
+    appearance: OverrideAppearance;
+    updatedAt?: string;
+    source?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONFIG: Config = {
+    darkTheme: "dark",
+    lightTheme: "light",
+    pollMs: 2000,
+    overrideFile: path.join(os.homedir(), ".pi", "agent", "system-theme-override.json"),
+    overrideMaxAgeMs: 60_000,
+};
+
+const GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "system-theme.json");
+const DETECTION_TIMEOUT_MS = 1200;
+const MIN_POLL_MS = 500;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeSettingValue(value: string): string {
+    const trimmed = value.trim().toLowerCase();
+    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) || (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+
+function toThemeName(value: unknown, fallback: string): string {
+    if (typeof value !== "string") return fallback;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function toPollMs(value: unknown, fallback: number): number {
+    if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+    return Math.max(MIN_POLL_MS, Math.round(value));
+}
+
+function extractStderr(error: unknown): string {
+    if (!error || typeof error !== "object") return "";
+    const stderr = (error as { stderr?: unknown }).stderr;
+    return typeof stderr === "string" ? stderr : "";
+}
+
+function parseOverrideAppearance(value: unknown): OverrideAppearance | null {
+    if (value === "dark" || value === "light" || value === "auto") return value;
+    return null;
+}
+
+function isDefaultThemeName(name: string | undefined): boolean {
+    return name === DEFAULT_CONFIG.darkTheme || name === DEFAULT_CONFIG.lightTheme;
+}
+
+function canManageThemes(ctx: ExtensionContext): boolean {
+    return ctx.hasUI && ctx.ui.getAllThemes().length > 0;
+}
+
+function isSSHSession(): boolean {
+    return !!(process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT);
+}
+
+// ---------------------------------------------------------------------------
+// Config I/O  (reads ~/.pi/agent/system-theme.json written by /system-theme)
+// ---------------------------------------------------------------------------
+
+async function loadConfig(): Promise<Config> {
+    const config = { ...DEFAULT_CONFIG };
+
+    // Read theme mapping from shared config (same file as pi-system-theme)
+    try {
+        const raw = await readFile(GLOBAL_CONFIG_PATH, "utf8");
+        const parsed = JSON.parse(raw) as unknown;
+        if (isObject(parsed)) {
+            config.darkTheme = toThemeName(parsed.darkTheme, config.darkTheme);
+            config.lightTheme = toThemeName(parsed.lightTheme, config.lightTheme);
+            config.pollMs = toPollMs(parsed.pollMs, config.pollMs);
+        }
+    } catch {
+        // missing or corrupt → use defaults
+    }
+
+    // Env overrides for bridge-specific settings
+    const envFile = process.env.PI_SYSTEM_THEME_OVERRIDE_FILE;
+    if (typeof envFile === "string" && envFile.trim().length > 0) {
+        config.overrideFile = envFile.trim();
+    }
+
+    const envMaxAge = process.env.PI_SYSTEM_THEME_OVERRIDE_MAX_AGE_MS;
+    if (envMaxAge) {
+        const v = Number.parseInt(envMaxAge, 10);
+        if (Number.isFinite(v)) config.overrideMaxAgeMs = Math.max(0, v);
+    }
+
+    return config;
+}
+
+async function saveConfig(config: Config): Promise<void> {
+    const overrides: Partial<Config> = {};
+    if (config.darkTheme !== DEFAULT_CONFIG.darkTheme) overrides.darkTheme = config.darkTheme;
+    if (config.lightTheme !== DEFAULT_CONFIG.lightTheme) overrides.lightTheme = config.lightTheme;
+    if (config.pollMs !== DEFAULT_CONFIG.pollMs) overrides.pollMs = config.pollMs;
+
+    if (Object.keys(overrides).length === 0) {
+        const { rm } = await import("node:fs/promises");
+        await rm(GLOBAL_CONFIG_PATH, { force: true });
+        return;
+    }
+
+    await mkdir(path.dirname(GLOBAL_CONFIG_PATH), { recursive: true });
+    await writeFile(GLOBAL_CONFIG_PATH, `${JSON.stringify(overrides, null, 4)}\n`, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Strategy 1: Override file
+// ---------------------------------------------------------------------------
+
+async function readOverrideFile(filePath: string, maxAgeMs: number): Promise<Appearance | "auto" | null> {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw) as unknown;
+        if (!isObject(parsed)) return null;
+
+        const appearance = parseOverrideAppearance(parsed.appearance);
+        if (!appearance) return null;
+
+        // Check freshness
+        if (maxAgeMs > 0) {
+            const updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined;
+            if (!updatedAt) return null;
+            const time = Date.parse(updatedAt);
+            if (!Number.isFinite(time) || Date.now() - time > maxAgeMs) return null;
+        }
+
+        return appearance;
+    } catch {
+        return null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Strategy 2: Terminal background color query (OSC 11)
+//
+// We spawn a short-lived subprocess that opens /dev/tty directly.
+// This avoids competing with pi's own stdin/stdout handling.
+// The query works transparently over SSH because escape sequences
+// travel through the SSH pseudo-terminal back to the local terminal.
+// ---------------------------------------------------------------------------
+
+const OSC11_QUERY_SCRIPT = `
+'use strict';
+const fs = require('fs');
+const net = require('net');
+
+let fd;
+try { fd = fs.openSync('/dev/tty', fs.constants.O_RDWR | fs.constants.O_NOCTTY); }
+catch { process.exit(1); }
+
+// Send OSC 11 query
+fs.writeSync(fd, '\\x1b]11;?\\x1b\\\\');
+
+// Read response with polling + timeout
+const buf = Buffer.alloc(512);
+let response = '';
+const deadline = Date.now() + 1500;
+
+function tryRead() {
+    try {
+        const n = fs.readSync(fd, buf, 0, buf.length);
+        if (n > 0) response += buf.toString('utf8', 0, n);
+    } catch {}
+}
+
+// Use a tight loop with small sleeps
+function poll() {
+    tryRead();
+    if (response.includes('\\x1b\\\\') || response.includes('\\x07') || Date.now() > deadline) {
+        fs.closeSync(fd);
+        // Parse rgb:RRRR/GGGG/BBBB  (16-bit) or rgb:RR/GG/BB (8-bit)
+        const m = response.match(/rgb:([0-9a-fA-F]+)\\/([0-9a-fA-F]+)\\/([0-9a-fA-F]+)/);
+        if (m) {
+            // Normalize to 8-bit (take first 2 hex chars of each component)
+            const r = parseInt(m[1].substring(0, 2), 16);
+            const g = parseInt(m[2].substring(0, 2), 16);
+            const b = parseInt(m[3].substring(0, 2), 16);
+            const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
+            process.stdout.write(luminance < 128 ? 'dark' : 'light');
+        }
+        process.exit(0);
+    }
+    setTimeout(poll, 20);
+}
+
+poll();
+`;
+
+function queryTerminalBackground(): Promise<Appearance | null> {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve(null);
+        }, 3000);
+
+        const child = spawn(process.execPath, ["-e", OSC11_QUERY_SCRIPT], {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3000,
+        });
+
+        let stdout = "";
+        child.stdout!.on("data", (chunk: Buffer) => {
+            stdout += chunk.toString();
+        });
+
+        child.on("close", () => {
+            clearTimeout(timer);
+            const trimmed = stdout.trim();
+            if (trimmed === "dark" || trimmed === "light") {
+                resolve(trimmed);
+            } else {
+                resolve(null);
+            }
+        });
+
+        child.on("error", () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Strategy 3: OS-level detection (fallback)
+// ---------------------------------------------------------------------------
+
+async function detectMacAppearance(): Promise<Appearance | null> {
+    try {
+        const { stdout } = await execFileAsync("/usr/bin/defaults", ["read", "-g", "AppleInterfaceStyle"], {
+            timeout: DETECTION_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        return normalizeSettingValue(stdout) === "dark" ? "dark" : null;
+    } catch (error) {
+        const stderr = extractStderr(error).toLowerCase();
+        if (stderr.includes("does not exist")) return "light";
+        return null;
+    }
+}
+
+async function detectLinuxAppearance(): Promise<Appearance | null> {
+    try {
+        const { stdout } = await execFileAsync("gsettings", ["get", "org.gnome.desktop.interface", "color-scheme"], {
+            timeout: DETECTION_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        const v = normalizeSettingValue(stdout);
+        if (v === "prefer-dark") return "dark";
+        if (v === "prefer-light") return "light";
+    } catch {
+        // ignore
+    }
+
+    try {
+        const { stdout } = await execFileAsync("gsettings", ["get", "org.gnome.desktop.interface", "gtk-theme"], {
+            timeout: DETECTION_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        const v = normalizeSettingValue(stdout);
+        if (v.includes("dark")) return "dark";
+        if (v.includes("light")) return "light";
+    } catch {
+        // ignore
+    }
+
+    return null;
+}
+
+async function detectWindowsAppearance(): Promise<Appearance | null> {
+    try {
+        const { stdout } = await execFileAsync(
+            "reg",
+            [
+                "query",
+                "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize",
+                "/v",
+                "AppsUseLightTheme",
+            ],
+            { timeout: DETECTION_TIMEOUT_MS, windowsHide: true },
+        );
+        const match = stdout.match(/AppsUseLightTheme\s+REG_DWORD\s+(\S+)/i);
+        if (!match) return null;
+        const raw = match[1] ?? "";
+        const num = raw.toLowerCase().startsWith("0x")
+            ? Number.parseInt(raw.slice(2), 16)
+            : Number.parseInt(raw, 10);
+        if (num === 0) return "dark";
+        if (num === 1) return "light";
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+async function detectOSAppearance(): Promise<Appearance | null> {
+    switch (process.platform) {
+        case "darwin":
+            return detectMacAppearance();
+        case "linux":
+            return detectLinuxAppearance();
+        case "win32":
+            return detectWindowsAppearance();
+        default:
+            return null;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Unified detection: override file → terminal query → OS detection
+// ---------------------------------------------------------------------------
+
+async function resolveAppearance(config: Config): Promise<Appearance | null> {
+    // 1. Override file (highest priority)
+    const override = await readOverrideFile(config.overrideFile, config.overrideMaxAgeMs);
+    if (override === "dark" || override === "light") return override;
+    // "auto" or null → continue
+
+    // 2. Terminal query via OSC 11 (works over SSH)
+    const fromTerminal = await queryTerminalBackground();
+    if (fromTerminal) return fromTerminal;
+
+    // 3. OS-level detection (local fallback)
+    return detectOSAppearance();
+}
+
+// ---------------------------------------------------------------------------
+// Interactive settings command  (/system-theme)
+// ---------------------------------------------------------------------------
+
+async function promptTheme(
+    ctx: ExtensionCommandContext,
+    label: string,
+    currentValue: string,
+): Promise<string | undefined> {
+    const next = await ctx.ui.input(label, currentValue);
+    if (next === undefined) return undefined;
+    const trimmed = next.trim();
+    return trimmed.length > 0 ? trimmed : currentValue;
+}
+
+async function promptPollMs(ctx: ExtensionCommandContext, currentValue: number): Promise<number | undefined> {
+    while (true) {
+        const next = await ctx.ui.input("Poll interval (ms)", String(currentValue));
+        if (next === undefined) return undefined;
+        const trimmed = next.trim();
+        if (trimmed.length === 0) return currentValue;
+        const parsed = Number.parseInt(trimmed, 10);
+        if (Number.isFinite(parsed) && parsed >= MIN_POLL_MS) return parsed;
+        ctx.ui.notify(`Enter a whole number ≥ ${MIN_POLL_MS}.`, "warning");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function systemThemeBridge(pi: ExtensionAPI): void {
+    let intervalId: ReturnType<typeof setInterval> | null = null;
+    let inFlight = false;
+    let config: Config = { ...DEFAULT_CONFIG };
+    let lastAppliedTheme: string | null = null;
+    let didWarnCustomTheme = false;
+
+    function hasThemeOverrides(): boolean {
+        return config.darkTheme !== DEFAULT_CONFIG.darkTheme || config.lightTheme !== DEFAULT_CONFIG.lightTheme;
+    }
+
+    function shouldAutoSync(ctx: ExtensionContext): boolean {
+        if (!canManageThemes(ctx)) return false;
+        if (hasThemeOverrides()) return true;
+        return isDefaultThemeName(ctx.ui.theme.name);
+    }
+
+    function maybeWarnCustomTheme(ctx: ExtensionContext): void {
+        if (didWarnCustomTheme || !canManageThemes(ctx) || hasThemeOverrides()) return;
+        const currentTheme = ctx.ui.theme.name;
+        if (isDefaultThemeName(currentTheme)) return;
+        didWarnCustomTheme = true;
+        ctx.ui.notify(
+            `Current theme "${currentTheme ?? "unknown"}" is custom. ` +
+                `Auto-sync skipped. Configure /system-theme to enable.`,
+            "info",
+        );
+    }
+
+    async function tick(ctx: ExtensionContext): Promise<void> {
+        if (!shouldAutoSync(ctx) || inFlight) return;
+
+        inFlight = true;
+        try {
+            const appearance = await resolveAppearance(config);
+            if (!appearance) return;
+
+            const targetTheme = appearance === "dark" ? config.darkTheme : config.lightTheme;
+            if (ctx.ui.theme.name === targetTheme && lastAppliedTheme === targetTheme) return;
+
+            const result = ctx.ui.setTheme(targetTheme);
+            if (result.success) {
+                lastAppliedTheme = targetTheme;
+            } else {
+                const msg = result.error ?? "unknown";
+                if (lastAppliedTheme !== `err:${targetTheme}:${msg}`) {
+                    lastAppliedTheme = `err:${targetTheme}:${msg}`;
+                    console.warn(`[pi-system-theme-ssh-bridge] setTheme("${targetTheme}"): ${msg}`);
+                }
+            }
+        } finally {
+            inFlight = false;
+        }
+    }
+
+    function restartPolling(ctx: ExtensionContext): void {
+        if (intervalId) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+        if (!shouldAutoSync(ctx)) return;
+        intervalId = setInterval(() => void tick(ctx), config.pollMs);
+    }
+
+    // -- /system-theme command (interactive settings) -------------------------
+
+    pi.registerCommand("system-theme", {
+        description: "Configure system theme sync (dark/light mapping, poll interval)",
+        handler: async (_args, ctx) => {
+            if (!canManageThemes(ctx)) {
+                if (ctx.hasUI) ctx.ui.notify("Requires interactive mode with themes.", "info");
+                return;
+            }
+
+            const draft: Config = { ...config };
+
+            while (true) {
+                const darkOpt = `Dark theme: ${draft.darkTheme}`;
+                const lightOpt = `Light theme: ${draft.lightTheme}`;
+                const pollOpt = `Poll interval (ms): ${draft.pollMs}`;
+                const saveOpt = "Save and apply";
+                const cancelOpt = "Cancel";
+
+                const choice = await ctx.ui.select("pi-system-theme-ssh-bridge", [
+                    darkOpt,
+                    lightOpt,
+                    pollOpt,
+                    saveOpt,
+                    cancelOpt,
+                ]);
+
+                if (choice === undefined || choice === cancelOpt) return;
+
+                if (choice === darkOpt) {
+                    const next = await promptTheme(ctx, "Dark theme", draft.darkTheme);
+                    if (next !== undefined) draft.darkTheme = next;
+                    continue;
+                }
+                if (choice === lightOpt) {
+                    const next = await promptTheme(ctx, "Light theme", draft.lightTheme);
+                    if (next !== undefined) draft.lightTheme = next;
+                    continue;
+                }
+                if (choice === pollOpt) {
+                    const next = await promptPollMs(ctx, draft.pollMs);
+                    if (next !== undefined) draft.pollMs = next;
+                    continue;
+                }
+                if (choice === saveOpt) {
+                    config = { ...config, darkTheme: draft.darkTheme, lightTheme: draft.lightTheme, pollMs: draft.pollMs };
+                    try {
+                        await saveConfig(config);
+                        ctx.ui.notify("Settings saved.", "info");
+                    } catch (e) {
+                        ctx.ui.notify(`Save failed: ${e instanceof Error ? e.message : String(e)}`, "error");
+                        return;
+                    }
+                    await tick(ctx);
+                    restartPolling(ctx);
+                    maybeWarnCustomTheme(ctx);
+                    return;
+                }
+            }
+        },
+    });
+
+    // -- /system-theme-push command (write override file) ---------------------
+
+    pi.registerCommand("system-theme-push", {
+        description: "Write override appearance: /system-theme-push dark|light|auto",
+        handler: async (args, ctx) => {
+            const first = String(args[0] ?? "").trim().toLowerCase();
+            const appearance = parseOverrideAppearance(first);
+            if (!appearance) {
+                if (ctx.hasUI) ctx.ui.notify("Usage: /system-theme-push dark|light|auto", "warning");
+                return;
+            }
+
+            const payload: OverridePayload = {
+                appearance,
+                updatedAt: new Date().toISOString(),
+                source: os.hostname(),
+            };
+
+            await mkdir(path.dirname(config.overrideFile), { recursive: true });
+            await writeFile(config.overrideFile, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+            if (ctx.hasUI) ctx.ui.notify(`Override written: ${appearance}`, "info");
+            await tick(ctx);
+        },
+    });
+
+    // -- Lifecycle ------------------------------------------------------------
+
+    pi.on("session_start", async (_event, ctx) => {
+        config = await loadConfig();
+
+        if (!shouldAutoSync(ctx)) {
+            maybeWarnCustomTheme(ctx);
+            return;
+        }
+
+        await tick(ctx);
+        restartPolling(ctx);
+    });
+
+    pi.on("session_shutdown", () => {
+        if (intervalId) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+    });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "pi-system-theme-ssh-bridge",
+    "version": "0.1.0",
+    "description": "Sync pi theme with system appearance — works locally and over SSH via OSC 11 terminal queries",
+    "keywords": [
+        "pi-package",
+        "pi",
+        "pi-coding-agent",
+        "theme",
+        "ssh",
+        "dark-mode",
+        "ghostty"
+    ],
+    "author": "mise42",
+    "license": "MIT",
+    "type": "module",
+    "files": [
+        "index.ts",
+        "push-theme-override.sh",
+        "README.md",
+        "LICENSE"
+    ],
+    "pi": {
+        "extensions": [
+            "index.ts"
+        ]
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mise42/pi-system-theme-ssh-bridge.git"
+    },
+    "homepage": "https://github.com/mise42/pi-system-theme-ssh-bridge#readme",
+    "bugs": {
+        "url": "https://github.com/mise42/pi-system-theme-ssh-bridge/issues"
+    }
+}

package/push-theme-override.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage:
+#   ./push-theme-override.sh desktop-hostname
+#   ./push-theme-override.sh user@192.168.1.88
+
+TARGET="${1:-}"
+if [[ -z "$TARGET" ]]; then
+  echo "Usage: $0 <ssh-target>"
+  exit 1
+fi
+
+if /usr/bin/defaults read -g AppleInterfaceStyle >/dev/null 2>&1; then
+  APPEARANCE="dark"
+else
+  APPEARANCE="light"
+fi
+
+UPDATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+SOURCE="$(hostname)"
+
+ssh "$TARGET" "mkdir -p ~/.pi/agent && cat > ~/.pi/agent/system-theme-override.json <<'JSON'
+{
+  \"appearance\": \"$APPEARANCE\",
+  \"updatedAt\": \"$UPDATED_AT\",
+  \"source\": \"$SOURCE\"
+}
+JSON"
+
+echo "Pushed appearance=$APPEARANCE to $TARGET"