🐙 LLMPET — Claude Code / Codex 桌面宠物

一个实时盯着 Claude Code 和 OpenAI Codex 的桌面宠物：它会随 agent 的状态变表情（思考 / 干活 / 等你授权 / 完成庆祝 / 睡觉），把 agent 的回复弹成气泡，并在详情面板里给出上下文、额度或花费、用量趋势与会话列表。Claude Code 需要授权时，还可以直接在桌宠上一键允许 / 拒绝。

现在可以直接下载使用： 普通用户无需安装 Node.js 或执行命令，前往 GitHub Releases 下载最新的 macOS / Windows 版本即可。源码安装方式仍保留给开发和调试使用。

共三款皮肤：章鱼 🐙、像素怪兽 👾、月薪喵 🐱（猫 meme 表情包，素材来自抖音 @月薪喵，见 assets/cat/CREDITS.md）。后端（状态机 / 计量 / 权限 / 进程对账）从零自有实现。Claude Code 通过公开 hook 接口接入；Codex 只读监听本机 rollout 文件，不修改 Codex 配置。

贡献者：@james6666-max — Windows 平台支持：「去回复」窗口聚焦、终端 pid 链解析与缓存、electron-builder 打包链路、CI Windows 测试矩阵（PR #6）。欢迎更多 PR！

月薪喵皮肤 × 状态

工作原理

Claude Code ──(生命周期 hook)──► octopus-hook.js ──HTTP POST /state──┐
            ──(PermissionRequest HTTP hook，阻塞)──► /permission ──┤
                                                                   ▼
                                              ┌──────────────────────────────┐
                                              │  本地 HTTP server (127.0.0.1) │
                                              └──────────────┬───────────────┘
                                                             ▼
            会话状态机 (core) ── 适配器 ── pet:stats / pet:event ──► 桌宠/面板渲染
            计量扫描 (metering) ── 读 ~/.claude transcript → 算 token & 花费 ─┘

1. 安装时往 ~/.claude/settings.json 注册两类钩子（合并写入，不覆盖你已有的钩子，卸载会先备份）：
   • 命令钩子：Claude Code 在 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop / SubagentStart … 触发 hook/octopus-hook.js，它读 stdin + transcript 尾巴，POST 一个状态包给本地 server（127.0.0.1:41330 起）。
   • PermissionRequest HTTP 钩子（阻塞）：需要授权时 Claude Code POST /permission 并挂起，等桌宠回 allow/deny。
2. 本地 server 把状态喂给会话状态机；适配器翻译成前端契约（pet:stats 快照 + pet:event 事件）。
3. 计量模块增量扫描 ~/.claude/projects/**/*.jsonl，按 message.id 去重统计每轮 token，乘模型单价算花费，喂详情面板。

**「Claude 客户端消息」**指的是 Claude Code（CLI agent）的回复内容——Stop 时从 transcript 抽最后一段 assistant 文本（截断 + 密钥脱敏），对应桌宠的 💬 气泡。（不是 Claude 桌面聊天 App 的消息。）

🛰️ Codex 后端（零配置、只读）

除 Claude Code 外，桌宠也能盯 OpenAI Codex（CLI / Desktop）：

Codex CLI / Desktop ──写 rollout──► ~/.codex/sessions/YYYY/MM/DD/*.jsonl
                                          │ (codex-watch 增量 tail，只读)
                                          ▼
                    同一个会话状态机 (core, agentId: 'codex') ──► 桌宠/面板

• 不装任何钩子：Codex 只有一个全局 notify 配置位（常被 ChatGPT 桌面 App 占用），所以走「监听 rollout 文件」——增量 tail、零配置、卸载无残留。
• 事件映射：user_message→思考；首个 exec_command/apply_patch 后整轮保持“干活中”（工具结果和中间 reasoning 不会误降成思考），直到 task_complete→完成庆祝+💬 或 turn_aborted→中断徽标；token_count→上下文%。guardian / auto-review 等 subagent 内部线程自动过滤，长会话恢复时只读取新增事件、不重放历史。
• 额度：Codex 没有逐 token 价目，面板显示套餐窗口用量（5h 主窗口 + 周窗口 %，来自 rollout 的 rate_limits）。
• 两种形态（托盘 → 设置 → 分身）：
  • 单宠（默认）：一只宠同时盯两个后端，会话列表用图标区分（Claude 橙 burst / Codex 蓝终端块）；
  • 双宠：Claude / Codex 各一只，形象、位置独立可拖，各自戴名牌，事件各归各的宠。
• LLMPET_NO_CODEX=1 关闭 Codex 监听；LLMPET_CODEX_DIR=<dir> 指向假目录做开发验证。

安装与运行

直接下载（推荐）

前往 Releases 下载最新版

• macOS（Apple Silicon）：下载 LLMPET-*-mac-arm64.zip，解压后打开 LLMPET.app。首次启动如被 macOS 拦截，请在 Finder 中右键应用选择“打开”；巡视其他桌宠还需要在系统设置中授予辅助功能权限。
• Windows（x64）：推荐下载 LLMPET-*-Windows-x64.exe 安装版；也可以下载同名 .zip 免安装版，解压后直接运行。

Release 包已包含 Electron 运行环境，不需要另行安装 Node.js、npm 或克隆仓库。首次启动会自动合并安装 Claude Code hooks，不会覆盖已有 hooks。

升级兼容说明： ~/.octopus、OCTOPUS_* 环境变量和 octopus-hook.js 是早期版本留下的内部兼容标识，为避免丢失配置、用量历史、辅助功能授权或已安装 hooks，1.0.0 继续保留；产品名称和所有对外发布物统一使用 LLMPET。

从源码运行

前置条件

• macOS 或 Windows（状态显示、授权气泡、计量计费、「去回复」终端聚焦全都可用；「领地模式」目前仅 macOS）
• Node.js ≥ 18（含 npm）
• 至少安装并使用过一个受支持的 agent：Claude Code 或 OpenAI Codex

git clone https://github.com/myunwang/LLMPET.git
cd LLMPET
npm install          # 装 electron（国内网络慢可加：ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install）
npm start            # 启动桌宠（首次启动会注册 Claude Code 钩子）

启动后新开的 Claude Code / Codex 会话会被感知；近期仍活跃的 Codex rollout 也会静默恢复到会话列表。右键桌宠可切三款皮肤和单宠/双宠模式。

Windows 说明

• 命令与上面相同（PowerShell 下设镜像用 $env:ELECTRON_MIRROR='https://npmmirror.com/mirrors/electron/' 再 npm install）。

• 钩子在 Windows 下经 PowerShell 运行；「去回复」通过 user32 把会话所在的终端窗口（Windows Terminal / cmd / VS Code 等）带到前台，Windows Terminal 多标签场景只能聚焦到窗口级别。

• 终端归属解析（pid 链）首次约 1–2s（起一次 PowerShell），之后按会话缓存在 ~/.octopus/pidwalk-cache.json，热路径无感。

• 打包安装版：npm run package:win（electron-builder，产出 NSIS 安装包 + zip；国内网络可另设 $env:ELECTRON_BUILDER_BINARIES_MIRROR='https://npmmirror.com/mirrors/electron-builder-binaries/'）。

• 首次启动会把钩子写进 ~/.claude/settings.json（合并、可逆）。之后新开的 claude 会话即被桌宠感知。

• 左键点桌宠 = 弹出会话列表（每行：状态点 + 会话名 + 上下文用量%），点某行把该会话的终端调到前台；没有会话时给「新开 Claude」按钮。

• 右键 = 泡泡菜单；拖动 = 移动位置。等授权/等回复时会自动弹允许/拒绝气泡。

• 托盘菜单可开详情面板、静音、唤起 Claude、打开日志、卸载钩子、退出。

• 详情面板里可切皮肤 / 模式 / 设 5h 预算。

• 🥊 领地模式（macOS）：右键桌宠点“巡视”可立即扫描并执行一次；托盘可开启“自动巡逻”，开启后立即首巡、随后定时轮询（默认关）。两条定律：①猫爪在上——检测到别的桌面宠物（Desktop Goose / BongoCat / Shimeji 等）在跑，就把自己的窗口层级抬到最上，谁也不许压着咱（无需额外权限）；②巡视行动——发现对方窗口，小章鱼走过去把它一步步顶到屏幕边上。巡视需要辅助功能权限（移动别人的窗口）；没授权时「巡视」仍会执行猫爪在上，只是不推窗。对付 AXPosition 失效的透明窗桌宠时，会像 Computer Use 一样显示独立的橙色爪软件光标；底层兼容拖拽仍只在你输入空闲 ≥2s 时执行，期间隐藏系统光标，结束或异常都会补发 mouseUp 并把原光标复位，你手上有活时则静默撤退。自定义对手：~/.octopus/config.json 的 territoryRivals 数组加进程名关键词。

开发 / 验证开关

• OCTOPUS_NO_HOOKS=1 npm start —— 启动但不动 ~/.claude/settings.json（只验证主进程 / 界面）。
• OCTOPUS_ALLOW_MULTI=1 npm start —— 跳过多实例防护（默认：实例锁 + 启动探测到别的 LLMPET 实例就退出 + 存活期间守护 runtime.json 不被其他副本抢走）。
• OCTOPUS_NO_NET=1 npm start —— 完全离线：关掉唯一的外联请求（每 24h 拉一次 LiteLLM 公开价目表，只下载、不上传任何本地数据），花费改用内置估算单价。
• OCTOPUS_DEBUG=1 npm start —— 开放 GET /debug（默认关闭，会暴露会话 cwd / 标题等，仅本机回环可访问）。
• OCTOPUS_TERRITORY_RIVALS=TextEdit OCTOPUS_TERRITORY_INTERVAL=4000 npm start —— 领地模式调试：临时追加对手进程名（逗号分隔）/ 调巡逻间隔（ms），配合托盘开关做实机验证。
• npm test —— 无头端到端冒烟测试（hook→server→core→adapter、权限持开→decide 字节级响应）。
• 日志：~/.octopus/octopus.log。

计量 / 计费

• 数据源：本机 ~/.claude/projects/**/*.jsonl（只读 token 数 / 模型 / 时间戳，不读内容）。
• 状态持久化：~/.octopus/usage.json（含 90 天日历、游标）。首次启动会回填近 95 天历史。
• 按完整 model id 精确计价：从 LiteLLM 公开价目表 同步每个模型的真实单价（opus 各代、fable、sonnet 各代各自独立），未同步时回退家族估算。可用 ~/.octopus/pricing.json 覆盖（家族键或精确 models 映射）：

  { "opus": {"input":15,"output":75,"cacheWrite":18.75,"cacheRead":1.5},
    "models": { "claude-fable-5": {"input":10,"output":50,"cacheWrite":12.5,"cacheRead":1} } }
  

  （单位：美元 / 百万 token。）
• 重算历史：改了定价、或想用最新价目纠正过去存错价的历史，跑 npm run meter:rebuild（从 transcript 真相源重扫重算、写回 usage.json；--no-sync 用现有缓存价、OCTOPUS_NO_NET=1 完全离线）。

卸载钩子

托盘「🧹 卸载 Claude 钩子」，或：

npm run uninstall:hooks

目录结构

main.js                 Electron 主进程：窗口 / IPC / 托盘 / 启动编排
preload.js              前后端唯一接口（contextBridge）
renderer/  assets/      桌宠 + 面板的视觉与渲染
hook/
  octopus-hook.js        Claude Code 触发的钩子脚本（读 stdin/transcript，POST /state）
backend/
  transport.js          端口发现 / runtime 文件 / 标识头 / 钩子→server 传输 / node 定位
  transcript.js         transcript 解析（assistant 文本 / 上下文用量 / API 错误 / 标题）
  pidwalk.js            进程树解析（定位会话所在终端）
  hookinstall.js        merge-safe 钩子安装器（合并不覆盖 / 原子写 / 卸载备份）
  launch.js             开终端跑 claude
  core.js               会话存储 + 状态机 + 快照 + 陈旧清理
  server.js             本地 HTTP server（/state /permission /health）
  permission.js         授权持开/决策（字节级 CC 响应）
  adapter.js            内部模型 → 前端契约（事件 + 统计 + choice）
  metering.js           计量 + 计费（transcript 扫描 + 定价 + 持久化）
  hooks.js              钩子生命周期（安装 + settings 监视器）
  focus.js              定位会话（mac 优先）
  territory.js          领地模式（扫描别的桌宠 + 推窗驱