# Cmux Wallpaper Switcher

> cmux（macOS 上的 Claude Code 终端客户端）换壁纸/背景图的技能。当用户想给 Claude Code 换壁纸、 换背景图、换终端背景、把某张图设为聊天背景、切换深浅色主题时触发。关键认知：Claude Code 跑在 cmux 内置的 ghostty 终端里，用户看到的"背景/壁纸"就是终端 ghostty 的背景图，不是 cmux 内置聊天 网页（改 app bundle 用户看不见）。内置一键脚本 set-background.py（复制图 + PIL 取主色 + 改 ghostty config + 改 cmux 左栏 tint + 备份），并附可读性判断规则和手动改法。

- Skill: `kevin204816/cmux-wallpaper-switcher` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kevin204816/cmux-wallpaper-switcher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kevin204816/cmux-wallpaper-switcher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Kevin204816 (https://skillmd.com/u/kevin204816)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kevin204816/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. **跑一键脚本**（推荐）：
   ```bash
   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. **校验**：
   ```bash
   /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+, 不生效，必须完全重启；
   重启会杀当前对话，**让用户择机，绝不擅自重启**。

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

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

| 图类型 | 文字区亮度 | theme | background-image-opacity | 兜底 background |
| --- | --- | --- | --- | --- |
| 深净图（中心暗） | < 90 | TokyoNight Night | 1.0 | 取图里最深的色 |
| 中调图（不深不浅） | 90–130 | TokyoNight Night | 0.55–0.6 | 深色压暗 |
| 浅色插画图 | > 130 | TokyoNight Day | 1.0 | 取图里最浅的色 |

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

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

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

```ini
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 只能纯色，
不能放图）：

```jsonc
"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"`，否则浅色
  模式下深底深字看不见。

## 生效规则汇总

| 改的项 | 生效方式 |
| --- | --- |
| 终端背景图 / theme / background | Cmd+Q 完全退出 cmux 再打开 |
| 左栏 tint / appearance | Reload（Cmd+Shift+,）；appearance 改动常需完全重启 |