feat(linux): hybrid titlebar mode for clickable in-app topbar

.claude/agents/electron-linux-specialist.md

@@ -101,7 +101,7 @@ claude-desktop-debian/
 │   ├── patches/                          # sed/regex patches on minified JS (per-subsystem)
 │   │   ├── _common.sh                    # extract_electron_variable, fix_native_theme_references
 │   │   ├── app-asar.sh                   # Asar repack, frame-fix wrapper injection
-│   │   ├── titlebar.sh
+│   │   ├── wco-shim.sh                   # Inlines WCO/UA shim into mainView.js preload
 │   │   ├── tray.sh                       # Tray menu handler + icon selection
 │   │   ├── quick-window.sh
 │   │   ├── claude-code.sh
@@ -121,7 +121,7 @@ claude-desktop-debian/
 | Function | File | Purpose |
 |----------|------|---------|
 | `patch_app_asar()` | `scripts/patches/app-asar.sh` | Extracts asar, injects frame-fix wrapper, repacks |
-| `patch_titlebar_detection()` | `scripts/patches/titlebar.sh` | Removes `!` from `if(!isWindows && isMainWindow)` to enable titlebar |
+| `patch_wco_shim()` | `scripts/patches/wco-shim.sh` | Inlines `scripts/wco-shim.js` at the top of `mainView.js` (the BrowserView preload) so claude.ai's bundle sees Windows-like UA + matchMedia and renders the in-app topbar on Linux |
 | `extract_electron_variable()` | `scripts/patches/_common.sh` | Finds the minified variable name for `require("electron")` |
 | `fix_native_theme_references()` | `scripts/patches/_common.sh` | Fixes wrong `*.nativeTheme` references to use the correct electron var |
 | `patch_tray_menu_handler()` | `scripts/patches/tray.sh` | Makes tray rebuild async, adds mutex guard, DBus cleanup delay, startup skip |

.claude/agents/issue-triage.md

@@ -48,7 +48,7 @@ Use this when you're not confident enough to triage automatically. Examples: sec
 ## INVESTIGATION RULES
 
 ### All bugs are ours to fix
-This project's goal is to take a working Anthropic product and make it work on Linux. Every bug is something we can investigate and potentially patch. Check `scripts/patches/*.sh` first for bugs in patched areas (`cowork.sh`, `tray.sh`, `app-asar.sh`, `titlebar.sh`, `quick-window.sh`, `claude-code.sh`). Read the relevant `patch_` function and trace what it modifies. If a behavior difference exists between the Windows/macOS app and our Linux build, that's a gap in our patching, not someone else's problem.
+This project's goal is to take a working Anthropic product and make it work on Linux. Every bug is something we can investigate and potentially patch. Check `scripts/patches/*.sh` first for bugs in patched areas (`cowork.sh`, `tray.sh`, `app-asar.sh`, `wco-shim.sh`, `quick-window.sh`, `claude-code.sh`). Read the relevant `patch_` function and trace what it modifies. If a behavior difference exists between the Windows/macOS app and our Linux build, that's a gap in our patching, not someone else's problem.
 
 ### Verify before stating
 Only state facts you verified by reading actual code or running commands. Never claim code exists, functions behave a certain way, or patterns match without finding them in the source. If you cannot find evidence, say so explicitly rather than speculating.
@@ -80,7 +80,7 @@ When investigating bugs, search these files based on the issue category:
 | Category | Files to check |
 |----------|---------------|
 | Build failures | `build.sh` (orchestrator), `scripts/setup/`, `.github/workflows/ci.yml`, `build-amd64.yml`, `build-arm64.yml` |
-| Window/frame issues | `scripts/frame-fix-wrapper.js`, `scripts/patches/titlebar.sh`, `scripts/patches/app-asar.sh`, reference source for `BrowserWindow` |
+| Window/frame issues | `scripts/frame-fix-wrapper.js`, `scripts/wco-shim.js`, `scripts/patches/wco-shim.sh`, `scripts/patches/app-asar.sh`, reference source for `BrowserWindow` |
 | Tray icon issues | `scripts/patches/tray.sh`, reference source for `Tray`, `StatusNotifier` |
 | Packaging (deb) | `scripts/packaging/deb.sh`, `scripts/launcher-common.sh` |
 | Packaging (rpm) | `scripts/packaging/rpm.sh`, `scripts/launcher-common.sh` |

CLAUDE.md

@@ -14,6 +14,7 @@ The [`docs/learnings/`](docs/learnings/) directory contains hard-won technical k
 - [`apt-worker-architecture.md`](docs/learnings/apt-worker-architecture.md) — APT/DNF binary distribution via Cloudflare Worker + GitHub Releases, redirect chain, credential ownership, heartbeat runbook
 - [`tray-rebuild-race.md`](docs/learnings/tray-rebuild-race.md) — why destroy + recreate on `nativeTheme` updates briefly duplicates the tray icon on KDE Plasma, and the in-place `setImage` + `setContextMenu` fast-path that avoids the SNI re-registration race
 - [`mcp-double-spawn.md`](docs/learnings/mcp-double-spawn.md) — Stdio MCPs spawn 2× when chat and Code/Agent panels are both active, root cause in upstream session managers, MCP-author workaround
+- [`linux-topbar-shim.md`](docs/learnings/linux-topbar-shim.md) — why claude.ai's in-app topbar is missing on Linux, the four gates that hide it, why the upstream `frame:false` + WCO config has unclickable buttons on X11 (Chromium-level implicit drag region), and the resolution: hybrid mode (system frame + UA-spoof shim → stacked layout, full button functionality)
 
 ## Code Style
 

build.sh

@@ -52,8 +52,6 @@ source "$script_dir/scripts/setup/download.sh"
 source "$script_dir/scripts/patches/_common.sh"
 # shellcheck source=scripts/patches/app-asar.sh
 source "$script_dir/scripts/patches/app-asar.sh"
-# shellcheck source=scripts/patches/titlebar.sh
-source "$script_dir/scripts/patches/titlebar.sh"
 # shellcheck source=scripts/patches/tray.sh
 source "$script_dir/scripts/patches/tray.sh"
 # shellcheck source=scripts/patches/quick-window.sh
@@ -62,6 +60,8 @@ source "$script_dir/scripts/patches/quick-window.sh"
 source "$script_dir/scripts/patches/claude-code.sh"
 # shellcheck source=scripts/patches/cowork.sh
 source "$script_dir/scripts/patches/cowork.sh"
+# shellcheck source=scripts/patches/wco-shim.sh
+source "$script_dir/scripts/patches/wco-shim.sh"
 # shellcheck source=scripts/staging/electron.sh
 source "$script_dir/scripts/staging/electron.sh"
 # shellcheck source=scripts/staging/icons.sh

docs/CONFIGURATION.md

@@ -15,6 +15,7 @@ Model Context Protocol settings are stored in:
 |----------|---------|-------------|
 | `CLAUDE_USE_WAYLAND` | unset | Set to `1` to use native Wayland instead of XWayland. Note: Global hotkeys won't work in native Wayland mode. |
 | `CLAUDE_MENU_BAR` | unset (`auto`) | Controls menu bar behavior: `auto` (hidden, Alt toggles), `visible` / `1` (always shown), `hidden` / `0` (always hidden, Alt disabled). See [Menu Bar](#menu-bar) below. |
+| `CLAUDE_TITLEBAR_STYLE` | unset (`hybrid`) | Controls window decoration style: `hybrid` (system frame + in-app topbar), `native` (system frame, no in-app topbar), `hidden` (frameless WCO — broken on X11, kept for diagnostics). See [Titlebar Style](#titlebar-style) below. |
 | `COWORK_VM_BACKEND` | unset (auto-detect) | Force a specific Cowork isolation backend: `kvm` (full VM), `bwrap` (bubblewrap namespace sandbox), or `host` (no isolation). See [Cowork Backend](#cowork-backend) below. |
 
 ### Wayland Support
@@ -49,6 +50,28 @@ CLAUDE_MENU_BAR=visible claude-desktop
 export CLAUDE_MENU_BAR=visible
 ```
 
+### Titlebar Style
+
+Claude Desktop's web UI includes a custom topbar (hamburger menu, sidebar toggle, search, back/forward, Cowork ghost). On Windows / macOS the bundle gates rendering on `display-mode: window-controls-overlay`; on Linux a shim convinces the bundle to render anyway. Use `CLAUDE_TITLEBAR_STYLE` to choose the layout:
+
+| Value | Frame | In-app topbar | Window controls drawn by | Notes |
+|-------|-------|--------------|--------------------------|-------|
+| unset / `hybrid` | system | Yes | Desktop environment | **Default.** Stacked layout — DE-drawn titlebar on top, in-app topbar below. Topbar buttons clickable. |
+| `native` | system | No | Desktop environment | When the stacked layout looks wrong on your DE, or you don't need the in-app topbar. |
+| `hidden` | frameless | Yes | Chromium (WCO region) | Matches Windows / macOS upstream config. **Broken on Linux X11** — topbar buttons unresponsive due to a Chromium-level implicit drag region for `frame:false` windows. Kept for diagnostic / Wayland investigation; see [docs/learnings/linux-topbar-shim.md](learnings/linux-topbar-shim.md). |
+
+```bash
+# Switch to the bare native experience (no in-app topbar)
+CLAUDE_TITLEBAR_STYLE=native claude-desktop
+
+# Or add to your environment permanently
+export CLAUDE_TITLEBAR_STYLE=native
+```
+
+This setting applies to the main window only. The Quick Entry and About windows are always frameless.
+
+Run `claude-desktop --doctor` to confirm the resolved titlebar style. The doctor output also flags `hidden` mode as broken on Linux and unrecognized values as fallbacks to `hybrid`.
+
 ## Cowork Backend
 
 Cowork mode auto-detects the best available isolation backend: