一个会浮在你桌面上的二次元小伙伴， 陪你开 Claude Code / Codex，在你写完代码、报错、等待时 奶声奶气地提醒你 —— 还会喊你「主人」哦 (´｡• ᵕ •｡`)
ฅ^•ﻌ•^ฅ (≧▽≦) (｡･ω･｡) >_< 🌸
启动 Claude Code（或 Codex）时，它会随机抽一个角色出现在桌面角落， 真透明、无边框，像真的小宠物一样浮在屏幕上。然后在关键时刻给你软萌提醒：
🎀 「主人，任务完成啦~ 要不要摸摸我奖励一下嘛 ✨」 🎀 「主人不好啦，代码闹脾气了 >_< 快来看看嘛~」 🎀 「主人~ 人家在等你哦，戳一下嘛 👉👈」
自带 6 个原创小可爱，更棒的是 —— 你可以放任何你喜欢的角色图（蕾姆、芙宁娜、皮卡丘、倒霉熊…随你！）。
| 🪟 真透明浮窗 | PySide6 逐像素透明，角色干净地浮在桌面，无背景无边框 |
| 🎲 随机出场 | 每次开会话随机抽一个角色陪你 |
| 💬 软萌提醒 | 完成 / 报错 / 等待 / 结束，都有可爱的「主人」文案 + 系统通知 |
| 🖼️ 自带角色 + 自定义 | 6 个原创吉祥物，外加你自己的任意 PNG/GIF |
| 🖱️ 可拖动 | 拖到任意位置，双击隐藏，右键换角色 |
| 🖥️ 跨平台 | macOS / Windows / Linux 都能用 |
| 🪶 零负担 | 不打扰、不抢焦点，纯本地运行，不联网 |
./install.sh然后在 Claude Code 里注册一次（以后每次开会话自动启动）：
/plugin marketplace add /你的路径/companion-pet
/plugin install companion-pet@companion-pet-marketplace
./install.ps1 # 自动建 venv、装 PySide6、把 hook 写进 settings.json装好后重启 Claude Code 即可。
💡 没有 PySide6 也没关系：会自动降级成 tkinter 卡片，再不行就纯系统通知，任何机器都能跑。
装好插件后什么都不用做 —— 每次开 Claude Code 会话，小可爱会自己蹦出来陪你 🎉
也可以手动用命令（macOS/Linux 用 bin/companion，Windows 用 bin\companion.cmd）：
bin/companion start # 让小可爱出场
bin/companion demo # 演示一遍所有提醒
bin/companion list # 看看角色池里都有谁
bin/companion add 图.png # 添加一个新角色
bin/companion stop # 让它先去休息
bin/companion status # 看看运行状态桌面上的交互： 🖐️ 拖动移动 · 👆👆 双击隐藏 · 🖱️ 右键 → 换一个角色 / 隐藏 / 退出
超简单！把图片丢进角色文件夹，自动加入随机池：
# 方法一：命令添加（推荐，自动放好）
bin/companion add ~/Downloads/蕾姆.png
# 方法二：直接把图片拖进这个文件夹
# macOS / Linux : ~/.companion/characters/
# Windows : %USERPROFILE%\.companion\characters\图片要求 📋
| 项目 | 要求 |
|---|---|
| 格式 | PNG 或 GIF（JPG 请先转 PNG，见下） |
| 背景 | 建议透明背景，浮在桌面最好看 |
| 尺寸 | 任意！会自动缩放，正方形最佳 |
| 名字 | 文件名 = 角色名字，由你自己定 🏷️ |
🏷️ 关于名字：桌面上不会显示名字标签（保持画面干净）。 但角色名 = 你的图片文件名，会出现在打招呼的气泡里 —— 比如文件叫
蕾姆.png，它就会说「蕾姆来陪主人啦~」。想叫什么，把文件改名就行； 不想要名字露出，把台词里的{name}删掉即可（见下方「改台词」）。
白底图想抠成透明？ 自带工具一键搞定（纯本地，不联网）：
# JPG 先转 PNG（macOS 自带 sips）：
sips -s format png 图.jpg --out 图.png
# 去白底变透明：
python3 scripts/remove_bg.py 图.png
# 白身体白背景（如线稿小熊）封不住开口？加大闭合半径：
COMPANION_CLOSE=16 python3 scripts/remove_bg.py 图.png🎯 挑图小贴士：选透明背景 / 纯色背景的角色立绘（render）最好； 带边框、文字、复杂背景的"卡片插画"不适合当桌宠哦。
完全免费、可商用、可公开分享（CC0，放心用）👇
| 来源 | 说明 |
|---|---|
| Kenney · itch 版 | 6 万+ 免费游戏素材，统一可爱风，CC0 零门槛 |
| itch.io chibi 精灵 · 免费筛选 | 一堆社区做的 Q 版小人 |
| いらすとや | 日本超火的免费可爱插画，海量小动物/吉祥物透明 PNG |
| OpenGameArt 等导航 | 免费游戏美术资源汇总 |
二次元角色透明 PNG（搜「角色名 + png/render」，个人本地使用）👇
PNGKey · CleanPNG · NicePNG · PNGAnime · PNGItem · PNGAAA · HiClipart
⚠️ 角色版权图仅建议个人本地当桌宠用，别二次分发/商用；想公开分享请用上面的 CC0 素材。
仓库 examples/characters/ 里放了几个抠好的示例角色，想用的话复制到你的角色文件夹即可：
# macOS / Linux
cp examples/characters/*.png ~/.companion/characters/
# Windows (PowerShell)
copy examples\characters\*.png $env:USERPROFILE\.companion\characters\
📛 版权声明 / Disclaimer：
examples/内的二次元角色图，版权归各自原作者 及版权方所有，此处仅作个人桌宠演示用途，不作任何商业用途。若版权方认为 不妥，请提 Issue，我会立即移除。 自带的assets/builtin/小可爱则是本项目原创，可自由使用。
想让它说别的？只要改一个文件：companion/messages.py 🖊️
里面是一张「事件 → 文案」表，每个事件对应 (通知标题, [气泡台词列表])，
随便加、随便删，保留 {name} 就能自动嵌进角色名：
_TEXT = {
"done": ("搞定啦主人~ ✅", [
"主人，任务完成啦~ 要不要摸摸我奖励一下嘛 ✨",
"搞定收工！主人好厉害呀 (≧▽≦)",
"{name}又帮主人搞定一件事 🎉", # ← {name} 会变成角色名
# 在这里加你自己的台词 👇
]),
...
}可改的事件：session_start（上线）· done（完成）· error（报错）· waiting（等待）· goodbye（结束）· idle（发呆）。
改完重启一下 bin/companion stop && bin/companion start 就生效啦~
| Claude Code 发生了… | 小可爱的反应 |
|---|---|
| 🟢 开始会话 | 蹦出来 + 「{name}来陪主人啦~」 |
| ✅ 回答完成 | 「主人，任务完成啦~」 |
| 「主人不好啦，代码闹脾气了 >_<」 | |
| 👀 等你确认 | 「主人~ 人家在等你哦」 |
| 👋 会话结束 | 「主人辛苦啦，记得早点休息哦 💤」 |
Claude Code 钩子 ─┐ ┌─ PySide6 透明浮窗（真·桌面宠物）
Codex notify ────┼─ companion ──本地TCP─────┤ ↘ 降级：tkinter 卡片
│ (任意 python3) +token └─ 系统通知（mac/win/linux）
└─ 浮窗起不来时，自动退回系统通知，绝不漏提醒
- GUI：PySide6（跨平台真透明）
- 通信：本地回环 TCP + 随机 token 鉴权（不开放端口、不联网）
- 通知：osascript(mac) / PowerShell toast(win) / notify-send(linux)
- 降级链：透明浮窗 → tkinter 卡片 → 纯通知，总有一档能用
除了插件自动出场，本项目还带一个 Claude Code Skill，让你直接用大白话管理桌宠：
「帮我启动桌宠」「把这张图加进桌宠」「我的桌宠有哪些角色」「换个角色」「改一下它说的话」
安装（让 Claude 能识别）：
mkdir -p ~/.claude/skills/companion-pet
cp -r skills/companion-pet/* ~/.claude/skills/companion-pet/之后在 Claude Code 里说一句「启动我的桌宠」就会触发啦~
插件（hooks）负责自动出场，Skill 负责对话控制，两者共用同一套 CLI，互补使用。
在 ~/.codex/config.toml 加一行：
notify = ["python3", "/你的路径/companion-pet/scripts/codex-notify.py"]这个小项目是用爱发电做的，希望能给每个敲代码的你带来一点点陪伴和快乐 (´｡• ᵕ •｡`)
- 🌟 喜欢的话，点个 Star 支持一下嘛~ 这是对作者最大的鼓励啦！
- 🐛 遇到 bug / 有想法？欢迎来 Issues 提，我会认真看每一条！
- 🎨 做了好看的角色 / 改了有趣的台词？欢迎 PR 分享给大家～
- 💌 不管是吐槽还是夸夸，都超欢迎，主人们的反馈是更新的动力！
⭐️ 仓库地址：
https://github.com/OvOhao/companion-pet（按你的实际仓库修改）