galaxy/specs/GH478/product.md

PRODUCT.md — Per-tab theme overrides driven by directory and launch configurations

Issue: https://github.com/warpdotdev/warp/issues/478 Related: https://github.com/warpdotdev/warp/issues/2618 (set warp theme in launch configuration)

Summary

The Warp theme is a single global value today (appearance.themes.theme in settings.toml); switching it affects every open tab at once. Users have asked for years (#478, 55+ upvotes; #2618) for tabs to render with different themes when they represent different contexts — different projects, local vs. remote machines, production vs. development.

This spec covers a focused first cut of per-tab theme overrides driven by three sources, in priority order:

1. A user-visible manual override on a tab (set via the launch configuration YAML or via a right-click menu).
2. A directory-pattern auto-match: the user maps directory paths to themes in settings.toml, and tabs whose active pane's cwd matches a pattern render with the mapped theme. This is the path most users in the issue thread describe (pyronaur, janderegg, milopersic): "I cd into project A, my theme should change."
3. A launch-configuration window-level default that themes every tab a given launch configuration opens unless the tab itself has another override.

The global theme remains the fallback when none of the three sources apply. Window chrome (title bar, sidebar, settings views, the tab strip) continues to follow the global theme so windows holding mixed-theme tabs remain visually coherent at the window level.

This spec deliberately scopes out automatic theming triggered by SSH host, hostname, runtime escape codes, or shell hooks. Those appear in #478 discussion and are listed as follow-ups that consume the override field this spec introduces.

Figma: none provided.

Goals / Non-goals

In-scope surfaces:

• A new settings map appearance.themes.directory_overrides whose keys are directory paths (tilde-expanded) and whose values are theme identifiers. Matching uses longest-prefix-wins.
• The launch-configuration YAML schema gains an optional theme: field at the tab level and at the window level.
• A persisted per-tab override that survives session restore.
• A right-click tab menu entry for Pin theme (manually override the active tab's theme to a chosen theme) and Reset theme (clear a manual override; cwd-pattern matching may then reapply).

Out of scope:

• SSH-host-driven, hostname-driven, or whoami-driven theming (stevenchanin, pyronaur, zethon, janderegg).
• Escape-code or shell-hook protocols for runtime theme switching (yatharth, for Claude-Code session signaling).
• Per-pane theming. Panes inside a tab continue to share one theme.
• Per-tab wallpaper or graphics (scottaw66, SheepDomination).
• Changes to the global theme storage path (appearance.themes.theme), the theme picker UI, or custom-theme loading. Overrides reuse the existing theme identifier type.

Resolution order

A tab's effective theme is determined by walking these layers and returning the first hit:

1. Menu pin, if any. Set by the right-click "Pin theme" menu and cleared by the right-click "Reset theme" menu. Persists across sessions.
2. Launch-configuration manual pin, if any. Set by a tab-level theme: in the launch configuration that opened (or restored) the tab. Cleared only by an explicit "Forget launch config theme" menu entry — Reset theme does not clear this layer (per Zach's v4 review). Persists across sessions.
3. Directory match, if any. The active pane's current working directory is matched against appearance.themes.directory_overrides; if a key is a prefix of the cwd, the longest such key wins.
4. Launch-configuration window-level default, if the tab was opened from a launch configuration with a window-level theme: and no closer override applies. Persists across sessions.
5. Global theme as derived from ThemeSettings and the system theme, exactly as today.

If none of the override sources resolve to a known theme, behavior is bit-for-bit identical to today.

Behavior

Directory-pattern overrides

1. settings.toml accepts a new section [appearance.themes.directory_overrides] whose entries map a directory path to a theme identifier. Example:

   [appearance.themes.directory_overrides]
   "~/Work/medone"   = "Dark City"
   "~/Work/bondwise" = "Solarized Dark"
   "~/Work/checkpt"  = "Dracula"
   

   Theme values are the same string form accepted by the global appearance.themes.theme (the parser tolerates both display names like "Dark City" and snake-case like "dark_city"; see #14 below).

2. Keys are tilde-expanded to absolute paths at match time. Trailing slashes are normalized away. Symlinks are not resolved — the cwd as the shell reports it is what's matched. Path normalization rules, per platform:

   • Linux: matching is case-sensitive (matches the filesystem semantics on standard ext4/xfs). Path separators are /.
   • macOS: matching is case-insensitive (matches the default HFS+/APFS case-insensitive setting). Path separators are /.
   • Windows: matching is case-insensitive. Both / and \ are accepted as separators in directory_overrides keys and are normalized internally to a single canonical form before comparison. Drive letters are normalized to uppercase (c:\Work and C:\Work are equivalent keys; the second-written one wins per TOML duplicate-key semantics). Tilde expands to %USERPROFILE%.

   Component-boundary matching (the rule in the previous paragraph that prevents ~/Work/medone from matching ~/Work/medone-archive) uses the platform's path-component definition — on Windows that means the boundary follows either \ or / after normalization.

3. Match resolution: a key matches if it is a prefix of the active pane's cwd at a path-component boundary. ~/Work/medone matches both ~/Work/medone and ~/Work/medone/apps/admin-api, but does not match ~/Work/medone-archive (no component boundary). When multiple keys match, the longest one wins (most specific).

4. The cwd evaluated for a tab is the cwd of the focused pane in that tab. A tab whose focused pane is in a non-shell context (notebook, settings view, etc.) has no cwd and falls through directory matching.

5. When a tab's active pane changes cwd (because the user ran cd, opened a subdirectory, or moved focus to a pane in a different cwd), directory matching re-runs. If the new cwd matches a different key, the tab immediately re-renders with the new theme. If it matches no key, the tab falls through to the next layer in the resolution order.

6. Adding, editing, or removing entries in directory_overrides while Warp is running re-evaluates every open tab. Tabs whose effective theme changes redraw; tabs whose effective theme is unchanged do not.

7. A theme name in directory_overrides that does not resolve to a known theme is treated the same way an unknown launch-configuration theme is (#11): a warning is logged identifying the offending key, the entry is skipped for matching purposes, and the rest of the map continues to work.

7a. directory_overrides is stored locally and never synced to Warp's cloud. Directory paths can encode employer, customer, and project names (~/Work/<client>/<engagement>/...); cloud-syncing the keys would push that organizational context off-machine. Users on multiple machines who want shared themes today set them per-machine. An opt-in cloud-sync mode is a candidate follow-up. The global theme setting (appearance.themes.theme) and per-tab pins set via the right-click menu remain user-controllable surfaces; only this map is local-only.

7b. Diagnostic output never contains raw directory_overrides keys. Local logs are routinely shared with Warp support and copied into bug reports, so even local diagnostics can leak path keys. The invariant is: any warning or telemetry emitted by the directory_overrides machinery refers to an offending entry by a short non-cryptographic hash of its key plus the offending value (the theme name, which is non-sensitive). For example, a warning that today might say directory_overrides: "~/Work/AcmeCorp/2026": unknown theme "Drakula" instead reads directory_overrides[hash=8a3f9c]: unknown theme "Drakula". The user can grep their settings.toml for the bad theme name to find the offending row. Hashes are stable for the same key but contain no path information.

Launch-configuration overrides

8. A launch configuration YAML may include theme: on any tab entry. Accepted values are theme identifiers in the form documented in #14. Omitting the field leaves the tab to fall through the resolution order.

9. A launch configuration YAML may include theme: on any window entry. Tabs in that window with no tab-level theme: and no directory match inherit this window-level value (per the resolution order: #3 sits below #2).

10. Saving a window's current state to a launch configuration preserves every theme override that was not derived from directory matching, so that reopening the saved configuration produces the same effective themes (modulo cwd matching, which re-runs against the current directory_overrides). Specifically, for each tab the preserved override is the first non-empty value of, in priority order: the tab's menu pin (layer #1), the tab's launch-configuration manual pin (layer #2), or the tab's window-level default (layer #4). Tabs whose effective theme came only from directory matching (layer #3) have no preserved override. The save rule is then:

    • If every tab in the window has the same preserved override Some(X) and no tab has a manual pin different from the others, the saved YAML emits a single window-level theme: X and no per-tab theme: fields.
    • Otherwise, each tab whose preserved override is Some(Y) emits a per-tab theme: Y; tabs with no preserved override emit no theme: field; window-level theme: is omitted.
    • Directory-matched themes never appear in saved YAML — directory matching is settings-level and re-applies on next open.

    This means a launch configuration that originally opened with a window-level theme: round-trips correctly: every tab inherited the value into its window_default slot, the save rule sees a shared preserved override, and emits the same window-level theme: again.

YAML / settings format

11. An unknown theme identifier — anywhere it appears — never causes a file-level load failure. The deserializer accepts any string; the resolver runs at apply time and falls back to the next resolution layer for the affected entry only. Other tabs in the same launch configuration, and other entries in the same directory_overrides map, are unaffected. Each unknown name produces exactly one logged warning per load.

12. Custom themes referenced by an override behave identically to custom themes used as the global theme — loaded from the user's themes directory, fail-soft to the next layer if the file is missing, same trust/validation rules as the global theme loader.

13. Overrides persist per-tab through session restore, by source:

    • Menu pin (layer #1) — kept on relaunch.
    • Launch-configuration manual pin (layer #2) — kept on relaunch. The launch configuration that set it is not necessarily reopened on restore, so the value travels with the tab.
    • Launch-configuration window-level default (layer #4) — kept on relaunch, same reason as #2.
    • Directory match (layer #3) — not stored; recomputed on relaunch from the current directory_overrides and the restored cwd. Editing directory_overrides between sessions therefore takes effect on the next launch.

14. The accepted form for any theme reference (in directory_overrides, in launch-config tab theme:, in launch-config window theme:) is a single string. Both the human-readable display form ("Dark City", "Solarized Dark", "Dracula") and the snake-case form ("dark_city", "solarized_dark", "dracula") are accepted. Matching is case-insensitive on whitespace-stripped input. Custom themes are referenced by their custom-theme name, same as today's global setting.

Rendering scope

15. When a tab has an effective override (from any layer), the override applies to: the terminal cell foreground/background, the ANSI 16-color palette used by the terminal grid, and any in-tab UI surfaces whose colors are derived from the active theme (block backgrounds, command output styling, accent colors). The window chrome (title bar, sidebar, settings views, the tab strip itself) continues to follow the global theme.

16. Switching tabs is instant — no flash, no progressive paint. Only the rendering of the newly-active tab reflects its (possibly different) theme; inactive tabs do not redraw on switch.

17. Changing the global theme updates every tab whose effective theme falls through to the global layer. Tabs with overrides at any higher-priority layer are unaffected.

User affordances

18. The right-click tab context menu gains three entries, alongside the existing per-tab attributes:

    • Pin theme... — opens a submenu listing available themes. Choosing one sets a menu pin on the tab (resolution layer #1), which wins over every other layer including a launch-config manual pin. Visible at all times.
    • Reset theme — clears only the menu pin (layer #1). The tab falls through to the launch-config manual pin / directory match / window default / global layers in that order. Visible only when the tab has a menu pin.
    • Forget launch config theme — clears only the launch-config manual pin (layer #2). The tab falls through to the directory match / window default / global layers. Visible only when the tab has a launch-config manual pin.

    Splitting "Reset theme" from "Forget launch config theme" means a user who pinned a different theme via the menu can clear that pin without unintentionally also discarding what their launch configuration originally set. (Per Zach's v4 review.)

19. The existing per-tab color: field on a tab template (the small colored indicator next to the tab title) is independent of the new theme override. Both can be set; both are honored.

20. The feature applies on every supported platform (macOS, Linux, Windows). It is gated behind a feature flag named appearance.themes.per_tab_overrides (per Zach's v4 review):

    • Initial release ships with the flag off in stable and on in dev/preview, so the rollout can soak with internal users before reaching the broader install base.
    • When the flag is off the feature is invisible: the right-click menu entries are hidden, directory_overrides matching does not run (the settings group is still parseable so users who set up the map under preview do not lose data), and launch-configuration theme: fields are deserialized but ignored. The user-visible behavior is bit-for-bit identical to today.
    • The default flips to on in stable in a follow-up release, after telemetry on the preview/dev cohort confirms no regressions in render performance, settings parsing, or session restore.
    • An empty directory_overrides map (the default) plus no launch-config theme fields plus no pinned themes — even with the flag on — is bit-for-bit identical to current behavior.

Accessibility

21. The override does not change any text content, accessible labels, or focus order. Screen readers continue to report tab titles and contents identically. The three new right-click menu entries have accessible labels "Pin theme" (with a submenu of theme names), "Reset theme", and "Forget launch config theme"; each is announced as a menu item, and each follows the menu's existing visibility rules (Reset theme appears only when the tab has a menu pin; Forget launch config theme appears only when the tab has a launch-config manual pin).

User-visible failure modes

• Unknown theme name — anywhere it appears, the entry is skipped at apply time, a one-line warning is written to the Warp log identifying the source (launch configuration filename + tab title or index for launch-config sources; redacted entry identifier for directory_overrides sources, never the raw path key — see #7b), and the rest of the configuration loads normally.
• Custom theme file missing — same fallback the global theme uses today: tab opens with the next-layer theme, warning logged.
• Two directory_overrides keys are equivalent after tilde expansion — last-write-wins per TOML semantics; a warning is logged identifying the duplicate.
• A pane's cwd is unavailable (non-shell pane content) — that pane contributes no cwd to directory matching; if it is the focused pane the tab falls through to the window/global layers.

Open questions

(Resolved in v4 review and folded into the spec — kept here as a record of the design choices made.)

• directory_overrides keys: glob vs. prefix matching. Resolved: prefix matching only (Zach v4: "i think prefix-match is fine to start"). Globs are a follow-up.
• "Reset theme" scope: clear all manual layers, or only menu pins. Resolved: only menu pins (Zach v4: "i don't think it should" clear launch-config pins). A separate "Forget launch config theme" entry exists for the launch-config layer. Reflected in behaviors #18 and in the resolution order.
• Should saving a launch configuration emit directory_overrides entries so themes travel with the launch config? Spec keeps the two surfaces independent — launch configs carry only manual pins; directory matching is settings-level and does not round-trip through saved launch configs. A future "shareable theme bundle" could compose them. Open for product-team input.