Cmux Wallpaper Switcher

cmux 换壁纸（终端背景图）

用户用 cmux（/Applications/cmux.app，开源 manaflow-ai/cmux）作为 Claude Code 的 macOS 客户端。 Claude Code 跑在 cmux 内置的 ghostty 终端里，用户天天盯着的"背景/壁纸"就是终端背景图。

不要改 cmux 内置聊天网页（app bundle 内 agent-session-react|solid 的 HTML/CSS/图片）—— 用户根本不打开那个 webview，改了也看不见。

标准流程（用户给一张图 / 说"换壁纸"，直接照做）

1. 拿到图片路径。终端里贴图有时读不到，让用户把图存成文件再给路径。
2. 跑一键脚本（推荐）：

   python3 scripts/set-background.py <图片路径>
   

   脚本会：复制图到 ~/.config/ghostty/background.png → PIL 取主色 → 改 ~/.config/ghostty/config （background-image / fit / position / opacity / background 兜底色 / theme）→ 改 ~/.config/cmux/cmux.json 左栏三个 tintColor → 自动备份旧配置。
3. 校验：

   /Applications/cmux.app/Contents/Resources/bin/ghostty +validate-config
   /Applications/cmux.app/Contents/Resources/bin/ghostty +show-config | grep background-image
   

   确认解析到图片、无报错。
4. 提醒用户 Cmd+Q 完全退出 cmux 再打开。终端背景项 Reload / Cmd+Shift+, 不生效，必须完全重启； 重启会杀当前对话，让用户择机，绝不擅自重启。

可读性判断（决定主题明暗和不透明度）

背景图压在文字下面，判断标准是文字区的亮度，不是整图平均：

• 图太花/太亮导致文字看不清时，降 background-image-opacity（0.85、0.6）让兜底色混入压一压。
• 从深色图换回浅色图，必须同时把 theme 改回 Day、opacity 改回 1。

手动改法（脚本失败 / 想自己调时）

改 ~/.config/ghostty/config 这几个键：

background-image = /Users/<you>/.config/ghostty/background.png
background-image-fit = cover
background-image-position = center
background-image-opacity = 0.55
background = #2B3950            # 图片加载前/透明处的兜底色
theme = TokyoNight Night        # 浅色图用 TokyoNight Day

改 ~/.config/cmux/cmux.json 的 sidebarAppearance 三个 tint 键为同一深色（左栏 native 只能纯色， 不能放图）：

"sidebarAppearance": {
  "tintColor": "#2B3950",
  "darkModeTintColor": "#2B3950",
  "lightModeTintColor": "#2B3950"
}

改前先备份：cp ~/.config/ghostty/config ~/.config/ghostty/config.bak-<描述>-<日期>、 cp ~/.config/cmux/cmux.json ~/.config/cmux/cmux.json.bak-<描述>-<日期>。

已知边界

• 背景图只在右侧终端区渲染，铺不满左栏 sidebar（左栏是 cmux native chrome，只能纯色 tint）。
• 左栏文字颜色跟 app 外观走、不跟 tint 自适应：深底必须同时设 app.appearance="dark"，否则浅色 模式下深底深字看不见。

生效规则汇总