Hopet

简体中文 · English

Hopet

一只常驻 macOS 桌面的 AI 宠物，用动画和气泡显示 Claude Code / Codex CLI 正在思考、执行工具、等待确认、请求权限或完成任务，并通过桌面宠物与灵动岛提醒你关注 agent 进展。

---

项目介绍

Hopet 是一只常驻 macOS 桌面的 AI 编程宠物，它把 Claude Code / Codex CLI 的会话状态变成可见、可感知的桌面反馈：思考、执行工具、等待确认、请求权限、完成或失败，都能通过宠物动画、气泡提示和灵动岛 / 顶部状态条表现出来。

它不是另一个聊天窗口，而是一个轻量的工作陪伴层，让开发者在写代码时不用频繁切回终端，也能直观看到 AI agent 当前在做什么、是否需要你介入，以及一次会话是否顺利推进。

Hopet 让本来隐藏在命令行里的 agent 生命周期变得更清楚、更亲近，也让长时间的 AI 协作多了一点秩序和温度。

发布版默认使用内置的 Hopi 主题——一只可爱的像素风小海豹，每个状态对应一段动画；如果你想换一只自己的宠物，可以准备一个名字和 8 张 GIF 图片，也可以直接导入 Codex pet 的文件夹或 ZIP 包。

支持的 AI 工具

Hopet 通过 agent CLI 的生命周期 hook 工作，目前覆盖以下 4 种用法：

• Claude Code——在任意终端里跑 claude CLI
• Claude Code for VS Code——官方 VS Code 扩展
• Codex CLI——在任意终端里跑 codex CLI
• Codex VS Code Extension——官方 VS Code 扩展

由于一切都走 ~/.claude/settings.json 和 ~/.codex/hooks.json 这两份 hook，所以宿主不影响行为：Apple Terminal、iTerm2、Ghostty、Warp、VS Code / Cursor 的内嵌终端等任一环境表现一致。

不支持：浏览器版 Claude（claude.ai）；以及非 Claude Code / Codex 的 AI agent（GitHub Copilot Chat、Gemini CLI、Aider 等）。

功能

会话感知

• 8 态状态机，覆盖 agent 的每一次有意义的转换：idle、responding、thinking、tool-use、permission-prompt、ask-user、completed、error-interrupted
• 多 session 聚合——所有活跃 session 共用一只宠物，宠物始终呈现优先级最高的那个状态（AskUser > Permission > Error > Tool > Thinking > Responding > Completed > Idle）
• Leader 高亮——驱动当前宠物状态的那个 session 会被显眼地标出来，让你一眼看清"是谁在找我"

Hook 集成

• 一键安装 / 卸载 Claude Code 与 Codex CLI 的 hook settings，采用安全的 JSON merge，绝不覆盖你已有的 hook
• Unix Domain Socket IPC，所有从 CLI helper 进入 App 的事件都走长度前缀 JSON 帧
• hopet-emit CLI 工具，完整支持 --require / --exclude / 点号嵌套字段路径——安装到 ~/.hopet/bin/，由注册好的 hook 直接调用
• 同步回包通道——PermissionRequest 和 AskUserQuestion 的答案沿着同一条挂起的 hook socket 回传给 agent，因此 Allow/Deny 和结构化答题在 iTerm、Apple Terminal、VS Code、Cursor、Ghostty、Warp 等所有终端宿主里行为一致

桌面宠物

• 悬浮 NSPanel——盖在普通窗口之上而不抢焦点，跨所有 Space，不出现在 ⌘Tab 循环里
• Sprite 动画——由当前主题驱动，Hopi 主题内置 8 段动画，状态切换时短暂交叉淡入
• 拖拽移动，位置自动记忆
• 内嵌交互气泡——权限请求会原位展开为 Allow / Deny / 交给终端 三选一卡片；AskUserQuestion 会展开为分页答题卡，每个问题提供选项按钮和自由文本兜底

灵动岛 / 顶部状态条

• 默认开启的刘海屏 Dynamic Notch——在 MacBook 刘海区域显示一条状态胶囊，跟随最高优先级 session 展示 Idle、Responding…、Thinking…、Running tool…、Permission needed、Waiting for your answer 等状态文案
• 展开交互——默认显示简短状态；点击或遇到权限请求、AskUserQuestion、完成摘要时展开为卡片
• 权限与提问可直接处理——展开后可在灵动岛里处理 PermissionRequest、AskUserQuestion 与 plan approval，结果通过 hook socket 同步回传给 agent
• 无刘海屏降级顶条——没有物理刘海的 Mac 可选择显示顶部中央状态条；默认关闭，避免遮挡菜单栏
• 开关位置——偏好面板 Overview → Display → Show notch bar 或 Behavior → Notch → Show notch bar 可实时开启 / 关闭；无刘海屏还需要打开 Behavior → Notch → Show top bar on non-notch displays

主题系统

• 内置 Hopi 主题——8 段像素海豹动画随 App 一同打包
• GIF 主题导入——填一个名字并准备 8 张 GIF（每个 PetState 一张）即可导入；导入时会校验文件格式和动画帧
• Codex pet 直接导入——选择 Codex pet 的文件夹 / ZIP 包，包内包含 pet.json 与 spritesheet.png 或 spritesheet.webp 即可。支持 v1（8×9）与当前 v2（8×11）图集，导入时会校验格式、尺寸与动画帧，并自动映射到 Hopet 状态
• 安全安装——两种导入方式都会将主题复制到 ~/.hopet/themes/<id>/ 并写入 manifest.json；任何一步失败都会整次回滚，目录里绝不会出现半成品
• 从偏好面板直接 Apply / Delete——用户主题和内置 Hopi 并存，App 升级后仍然保留

偏好面板

标准 macOS 偏好窗口，共 8 个 Tab：

Tab	用途
Overview	宠物当前状态快照与活跃 session 列表
Themes	内置主题 + 用户主题，导入 / 应用 / 删除
Appearance	宠物渲染相关选项
Bindings	全局主题绑定
Hooks	Claude Code / Codex hook 安装状态与诊断
Behavior	拖拽吸附、灵动岛 / 降级顶条、终端与诊断相关偏好
Notifications	各类横幅通知的分类开关
About	版本号、构建号、致谢