🐾 Companion Pet · 桌面陪伴小精灵
“主人~ 人家来陪你写代码啦 ✨”
一个会浮在你桌面上的二次元小伙伴,
陪你开 Claude Code / Codex,在你写完代码、报错、等待时
奶声奶气地提醒你 —— 还会喊你「主人」哦 (´。• ᵕ •。`)
ฅ^•ﻌ•^ฅ (≧▽≦) (。・ω・。) >_< 🌸
🌟 这是什么
启动 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,放心用)👇
二次元角色透明 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 就生效啦~
🪄 什么时候会提醒我