
claude-pet
🐾 macOS desktop pet: turn your own pet's photos/videos into a living desktop companion via fully-offline AI matting; reacts to your Claude Code sessions
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up claude-pet (release-binary project) into my current project. Found on https://claudeers.com/claude-pet-2 Repo: https://github.com/Sabrina-creater/claude-pet Homepage/docs: — Detected install method: release-binary → inspect the README Category: productivity. Platforms: cli, api, desktop, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: slowing; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/Sabrina-creater/claude-pet/releases
git clone https://github.com/Sabrina-creater/claude-pet
// compatibility
| Platforms | cli, api, desktop, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
Claude Pet 🐾

A macOS desktop pet that lives above all your windows — feed it, walk it, turn your own pet's photos/videos into its skin via fully-offline AI matting (Apple Vision framework), and watch it react to your Claude Code sessions. PySide6 + QML + three.js in QtWebEngine.
Not affiliated with or endorsed by Anthropic. "Claude" is a trademark of Anthropic PBC; this is a community project that merely talks to your locally installed Claude Code CLI. 本项目为社区作品,与 Anthropic 无关联;宠物本体功能不依赖 Claude、完全离线。
✨ 能干什么
| 🐶 你家宠物本尊上桌面 | 🍗 养成互动 | 🤖 Claude Code 联动 |
|---|---|---|
| 拍照/拍段视频 → 本地 AI 抠图(系统 Vision 框架,离线、免费、不排队)→ 变成会呼吸、走路、吃饭、睡觉的桌宠 | 投喂 / 摸摸 / 玩球 / 睡觉 / 🚶遛弯,攒经验升级;饿了会喊你 | 会话在跑时头顶转 ⚙️,干完活撒花庆祝,等你回复时蹦跶 + 系统通知;点宠物直接续聊 |

右键宠物 → 喂养菜单:投喂 / 互动 / 换形象;「我的模型」区 ➕ 上传 3D 模型(.glb/.gltf) 或 🎬 创建动画宠物,左右滑动挑选、长按拖动排序
![]() | ![]() |
| 点宠物 → 我的 Claude 会话:谁在干活、谁在等你回复,实时同步;点进去看历史、直接续聊、一键关会话 | 🎬 动画宠物 · 活动槽编辑器:六个动作逐槽上传照片/视频,本地 AI 抠图自动透明,✅ 实时标记进度 |

「睡觉」槽 = 你家狗睡觉的照片,连地板反光都保留 —— 六个活动槽(待机/走路/吃饭/睡觉/玩耍/开心)逐槽上传,宠物按状态自动切换
📦 下载安装
- 到 Releases 下载最新
ClaudePet-*.dmg(约 216MB,QtWebEngine 固有体量) - 把
Claude Pet.app拖进「应用程序」 - 首次打开提示「已损坏,无法打开」? 这是 macOS 对未公证应用的拦截(个人项目没买 $99/年的开发者账号),App 本身没坏:
- 双击 DMG 里附带的
修复「已损坏」提示.command即可(如果它也被拦,右键它 → 打开) - 或终端执行:
xattr -cr "/Applications/Claude Pet.app" - 注意:Apple 芯片 (M1/M2/M3) 上右键 App → 打开 是绕不过去的,必须用上面两种方式之一
- 双击 DMG 里附带的
- 打开后宠物出现在屏幕右下角,菜单栏会有 🐱 图标。看不到菜单栏图标? 刘海屏 MacBook 菜单栏满了会把新图标挤掉——不影响使用,所有操作(大小/形象/退出)右键宠物都有;想找回图标就清理几个菜单栏项或用 Ice/Bartender
- 以后有新版会自动提示更新(每天静默检查一次 GitHub Releases,一键下载换包重启);也可托盘「⬆️ 检查更新」手动查
系统要求:macOS 14+(AI 抠图依赖系统 Vision"提取主体"能力;13 可运行但照片/视频抠图不可用)。当前发布包为 Apple 芯片 (arm64) 构建,Intel Mac 需自行从源码打包。会话联动需本机装有 Claude Code(可选,不装只影响该功能)。
🚀 三步上手
- 右键宠物 → 喂养菜单(单击 = 会话面板,双击 = 摸摸,拖动 = 挪位置)
- 「我的模型」→ 🎬 动画宠物 → 按提示给各活动槽上传你家宠物的照片/视频(jpg/heic/mp4/mov/gif 都行,自动抠图秒级生效;方向不对点 ↻)
- 开着 🚶 遛弯,它会自己在屏幕上散步;写代码时它盯着你的 Claude Code 会话
住在你桌面上的 3D 宠物:18 种形象可换、可喂养、会对 Claude Code 会话有反应。
它会干什么
- 3D 本体:Three.js 渲染的卡通宠物,转头看你的鼠标、呼吸、眨眼、随机东张西望;翅膀/触手等部件有各自的小动作
- 看会话:角标 = 最近 48 小时会话数;Claude 在干活时它头顶转 ⚙️ 陪你"上班",干完活会跳起来转圈撒彩带(还涨经验),有会话等你时它会蹦跶提醒(角标变红)
- 能喂养:饱食🍗 / 心情💗 / 精力⚡ 三条状态随时间衰减(关掉 App 也在掉,封顶 24h),喂食、抚摸、玩毛线球、睡觉都会影响数值;攒经验升级
- 会说话:吃饱了、饿了、被摸了、干完活了……头顶冒中文气泡
操作
| 动作 | 效果 |
|---|---|
| 单击宠物 | 会话面板(状态/Todo 进度/续聊,同旧版) |
| 右键宠物 | 喂养菜单:状态条、投喂(小鱼干/苹果/蛋糕/咖啡)、摸摸/玩球/睡觉/🚶遛弯、形象切换、➕ 上传 .glb 模型、🎬 创建动画宠物 |
| 双击宠物 | 摸摸(冒爱心,心情+) |
| 拖动 | 移动位置(自动记住) |
| Esc | 关面板/菜单 |
21 形象:🐱小猫 👻幽灵 🦫卡皮巴拉 🦉猫头鹰 🦆小鸭 🪿大鹅 🫧泡泡 🐉小龙 🐙章鱼 🐧企鹅 🐢乌龟 🐌蜗牛 🦎六角恐龙 🌵仙人掌 🤖机器人 🐰兔兔 🍄蘑菇 😺胖墩,以及三只真模型:
- 🐈 高级猫(Sketchfab,带骨骼,坐姿/理毛/哈欠/甩尾;睡觉定格在闭眼蜷缩帧)
- 🦊 高级狐狸(Khronos 官方样例 Fox,CC0 by PixelMannen / rig CC-BY tomkranis,Survey 待机)
- 🦜 高级鹦鹉(three.js 官方样例 Parrot,CC-BY mirada/rome,形变飞行动画,悬浮)
上传自己的模型:右键菜单"➕ 上传模型"选一个 .glb/.gltf,自动归一化(居中/缩放/贴地)成新形象。带骨骼动画的会播动画;没动画的(如 Tripo 图生 3D)走全程序化(呼吸/看鼠标/吃饭/蹦跳),保持模型自身姿态。模型存 ~/Library/Application Support/claude-pet/models/,悬停模型格按 ✕ 删除。建议先把模型简化到 <5MB(npx @gltf-transform/cli optimize),太大(几十万面)会卡。
🎬 动画宠物(不会建模也能养):右键菜单点"🎬 动画宠物"创建,自动初始化 6 个活动槽(待机/走路/吃饭/睡觉/玩耍/开心),槽位编辑器逐槽引导上传。素材自动路由:
- 真实照片(jpg/heic)/ 视频(mp4/mov)→ 本地 AI 抠图(matting.py):Vision 框架(系统"提取主体"同源,Apple 芯片硬件加速)逐帧抠出主体 → 透明动画 WebP,视频 1-5 秒出结果,全程离线不排队——顺带绕开 WebEngine 没有 H.264 解码器的限制
- GIF/WebM → 纯色背景自动色键成透明(边框取样 + 自适应容差,GIF 抖动调色板也能识别);自带透明的素材原样用
至少上传「待机」;缺的动作自动回退到待机。宠物按状态切槽播放,上传/重传立刻热生效(文件名带时间戳)。拍你家宠物不同动作的短视频逐槽上传,桌宠就是它本狗/本猫;单张照片也行(呼吸/蹦跳/转向由渲染层实时加)。素材存 models/<key>/ 子目录,索引损坏可从子目录自愈重建。
🚶 桌面遛弯:宠物会自己在屏幕上走动(默认开,互动区可关):歇几秒挑个目标点走过去,走路时播「走路」槽动画并自动转向。拖动宠物、开面板/菜单、睡觉时自动暂停。
养成数值:喂食 +饱食/+心情/+5xp(>95 拒食),抚摸 +心情/+2xp,玩球 +心情/-精力/+8xp(精力<15 玩不动),睡觉回精力(太困会自己睡,睡饱自己醒);Claude 每干完一轮活 +15xp。每 100xp 升一级。
运行
./run.sh # 首次自动建 .venv 并装 PySide6-Essentials + Addons(WebEngine)
.venv/bin/python pet.py --dump # 不开窗口,纯打印会话扫描结果
.venv/bin/python pet.py --demo # 自动演示一轮喂食/摸摸/玩球/睡觉,21s 后退出
.venv/bin/python pet.py --probe # 每 2s 打印窗口几何/可见性,15s 后退出(诊断用)
.venv/bin/python pet.py --animdemo idle.gif walk.gif eat.gif
# 动画宠物全链路冒烟:创建→逐槽导入→喂食→遛弯,40s 自动清理退出
没装上 PySide6-Addons(WebEngine)时自动退回旧版 2D 小猫,功能不缺。
打包成独立 App(分发给别人)
打成 macOS .app + .dmg,对方无需装 Python,双击即用:
./packaging/build-mac.sh # 一键:PyInstaller 出 .app,再打 dist/ClaudePet.dmg
要点:
- 成品约 515MB(QtWebEngine 固有体量),
.app内含 qml/web/cat.glb 与完整 Qt 运行时 - 只能在 macOS 上构建 macOS 包,在 Windows 上构建 Windows 包(PyInstaller 不能跨系统);本仓库当前只配了 Mac
- 产物是 arm64(Apple 芯片)。Intel Mac 需在 Intel 机器上重跑构建
- 未签名 → 对方首次打开会被 Gatekeeper 拦(Apple 芯片上直接提示「已损坏」,右键打开也无效)。DMG 里已附带
修复「已损坏」提示.command双击即修;或终端xattr -cr "/Applications/Claude Pet.app" - 打包后仍是后台型(无 Dock 图标);退出用面板里的"退出宠物"或
pkill -f "Claude Pet" - 宠物本体(养成/3D)不依赖 claude CLI;只有"看会话/续聊"需要对方装了 Claude Code
资源定位:pet.py 的 resource_dir() 在打包后走 sys._MEIPASS,直跑时走脚本目录;打包配置见 claude-pet.spec。
架构
pet.py PySide6:会话扫描、养成状态机(衰减/持久化)、续聊子进程
qml/Main.qml 悬浮窗 + 气泡 + 面板/菜单窗口管理
qml/Pet3DBody.qml 透明 WebEngineView + 鼠标交互(单击/双击/右键/拖动)
qml/PetMenu.qml 喂养菜单(右键)
qml/PanelContent.qml 会话列表 + 聊天页
qml/PetBody.qml 2D 后备小猫(无 WebEngine 时)
web/index.html Three.js 宿主页(透明背景)
web/js/pet3d.js 渲染层:18 宠物加载归一化、IBL 三点光、看鼠标转头、
呼吸/眨眼、吃饭/摸摸/玩球/庆祝状态机、emoji 粒子
web/js/buddies.js 18 个程序化宠物模型(来自 claude-buddy-desktop)
web/js/GLTFLoader.js GLB 加载器(高级猫用;import 路径改成了同目录)
web/assets/cat.glb 高级猫模型(Sketchfab,带骨骼 + 10.8s sit_A 动画)
web/js/three.module.js Three.js(本地,离线可用)
GLB 模型接入要点(再加新模型时照抄):
- 防"公转":cat.glb 根节点自带 ~30 单位枢轴偏移,直接旋转会绕大圆;
加载后按蒙皮采样的真实包围盒(
getVertexPosition,蒙皮/morph 都覆盖)把内容中心平移回原点再缩放 - 绑定姿态的 bbox 不可信(猫尾伸直),要先
mixer.update()推进到动画姿态再量 - 待机动画整段循环,不要切片(旧项目硬切 5 段导致接缝闪烁);多段动画用
idleClip按名挑 - 毛发壳材质用半透明混合(
opacity 0.26 + alphaTest 0.04 + depthWrite false), 目标观感:体表干净色块、毛只在剪影边缘积累(两层毛壳叠加,单层要压很低); 纯 cutout 会"一茬一茬",透明度过高整身蒙霜 sleepPoseT: 睡觉时把待机动画定格在闭眼帧的时间点(cat.glb 是 5.0s)- Chromium 节流:透明悬浮窗会被判成"被遮挡",rAF 掉到 ~6fps 动画慢放;
必须带
--disable-backgrounding-occluded-windows等三个 flag(pet.py 已设)
Python ↔ JS 走 QWebChannel:petJson 属性(状态)+ petEvent 信号(互动事件)+ cursorMoved 信号(视线)+ walkChanged 信号(遛弯走/停/方向)+ userModelsJson 属性(用户模型,anim 类型带 slots 槽位表);宠物状态存 ~/Library/Preferences 的 pet.state。
动画宠物渲染要点:素材帧(ImageDecoder 解 GIF/WebP,<video> 解 MP4/WebM)画进 canvas → CanvasTexture 贴在竖立平面上挂进 body 组,呼吸/跳跃/影子/粒子全部复用 3D 管线;toneMapped=false 保原色;走路用 mesh.scale.x=-1 翻转。抠图见 detectBg/keyInPlace(边框众数桶做种子 → 色距<120 收内点 → 内点均值当背景色,按离散度自适应容差)。
浏览器单独调试渲染层:直接开 web/index.html?demo=1(需关 CORS 或本地 server),window.PET.do('eat',{food:'fish'}) 手动触发动画。
数据从哪来(全部只读)
| 来源 | 用途 |
|---|---|
~/.claude/projects/*/*.jsonl | 会话 transcript → 状态 / 标题 / Todo 进度 / 聊天历史 |
~/.claude/sessions/<pid>.json | 活着的 claude 进程 → 哪些会话"开着"、在终端还是桌面端 |
状态判定规则:
- transcript 15 秒内有写入 → 正在干活
- 进程活着但没在写 → 开着 · 等你(最后停在工具调用上则提示可能等授权)
- 进程已退出:最后一条是 Claude 的回复 → 等你回复;停在工具调用/你的消息上 → 已中断
- 超过 2 小时没动静 → 空闲
聊天页注意
- 续聊走
claude -p --resume <id> --output-format stream-json,在会话原目录执行 - "正在干活"的会话禁止插话(避免并发写 transcript)
- 在桌面端/终端开着的会话可以发,但对方界面不会实时刷新(会有黄条提醒)
- "自动同意文件编辑" =
--permission-mode acceptEdits;不开的话,需要权限的操作会被拒绝 - 某些情况下续聊会 fork 出新 session id,宠物会自动跟过去
窗口行为
悬浮在状态栏层级(level 25):所有空间可见、全屏 App 上方也显示;accessory 模式无 Dock 图标。退出靠面板里的"退出宠物"或 pkill -f pet.py。
白影防护(v1.4.3 起多层):默认软件合成(--disable-gpu-compositing,从机制上消灭"旧 GPU 表面残留成白影",CPU 约 +7%,CLAUDE_PET_GPU=1 可换回)+ macOS 15 窗口属性互斥修复(NSPanel 不抢焦点)+ 锁屏自动藏窗/解锁重建 + 关面板重建表面 + WebGL 上下文丢失即藏画布。
开机自启(可选)
~/Library/LaunchAgents/com.claude-pet.plist 指向 run.sh 即可,或加到"登录项"。
卸载
rm -rf 本目录即可,没有任何系统级改动(只有 ~/Library/Preferences 里位置和宠物状态两条记录)。
许可与致谢
代码 MIT(见 LICENSE);三方模型/库的许可与"仓库不含哪些模型、如何自备"见 NOTICE.md 与 web/assets/README.md。 高级猫/我的狗两个模型因许可与隐私不入库,缺失时自动退回程序化形象,不影响运行。
隐私:会话功能只读 ~/.claude 本地文件、抠图走 macOS 系统框架,全程无网络请求、无遥测。
// faq
What is claude-pet?
🐾 macOS desktop pet: turn your own pet's photos/videos into a living desktop companion via fully-offline AI matting; reacts to your Claude Code sessions. It is open-source on GitHub.
Is claude-pet free to use?
claude-pet is open-source under the MIT license, so it is free to use.
What category does claude-pet belong to?
claude-pet is listed under productivity in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/claude-pet-2)
// retro hit counter
[](https://claudeers.com/claude-pet-2)
// reviews
// guestbook
// related in Productivity
Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.
Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork
Garry's Opinionated OpenClaw/Hermes Agent Brain
An open-source alternative to Claude Cowork (powered by opencode)

