companion-pet

---

🌟 这是什么

启动 Claude Code（或 Codex）时，它会随机抽一个角色出现在桌面角落， 真透明、无边框，像真的小宠物一样浮在屏幕上。然后在关键时刻给你软萌提醒：

🎀 「主人，任务完成啦~ 要不要摸摸我奖励一下嘛 ✨」 🎀 「主人不好啦，代码闹脾气了 >_< 快来看看嘛~」 🎀 「主人~ 人家在等你哦，戳一下嘛 👉👈」

自带 6 个原创小可爱，更棒的是 —— 你可以放任何你喜欢的角色图（蕾姆、芙宁娜、皮卡丘、倒霉熊…随你！）。

---

✨ 特性

🪟 真透明浮窗	PySide6 逐像素透明，角色干净地浮在桌面，无背景无边框
🎲 随机出场	每次开会话随机抽一个角色陪你
💬 软萌提醒	完成 / 报错 / 等待 / 结束，都有可爱的「主人」文案 + 系统通知
🖼️ 自带角色 + 自定义	6 个原创吉祥物，外加你自己的任意 PNG/GIF
🖱️ 可拖动	拖到任意位置，双击隐藏，右键换角色
🖥️ 跨平台	macOS / Windows / Linux 都能用
🪶 零负担	不打扰、不抢焦点，纯本地运行，不联网

---

🚀 安装

macOS / Linux

./install.sh

然后在 Claude Code 里注册一次（以后每次开会话自动启动）：

/plugin marketplace add /你的路径/companion-pet
/plugin install companion-pet@companion-pet-marketplace

Windows（PowerShell）

./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 就生效啦~

---

🪄 什么时候会提醒我