简体中文 · 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	版本号、构建号、致谢

其中灵动岛总开关是 Show notch bar：在 Overview 的 Display 卡片和 Behavior 的 Notch 卡片里是同一个设置，切换后会立即显示或隐藏。无刘海屏机器若想显示顶部降级条，还需要额外打开 Show top bar on non-notch displays。

效果展示

Hopi 主题覆盖全部 8 个 PetState，下方每张 GIF 就是 App 内实际播放的动画，按优先级从高到低排列。

Ask User	Permission Prompt	Error / Interrupted	Tool Use
Thinking	Responding	Completed	Idle

安装

环境要求：macOS 14+，Apple Silicon。当前发布的 v0.1.2 DMG 暂不提供 Intel 二进制；Intel Mac 可从源码构建。

1. 从 Releases 页面 下载 Hopet-0.1.2.dmg。
2. 打开 DMG，把 Hopet 拖进 Applications。
3. 当前发布版本使用 ad-hoc 签名（无 Apple Developer ID），首次打开会被 macOS 拦截，提示「无法打开 Hopet，因为 Apple 无法检查其是否包含恶意软件」。两种绕过方式任选其一：
   • 在 Applications 里右键 Hopet.app → 打开 → 弹窗里再点一次打开；
   • 终端执行一次：xattr -dr com.apple.quarantine /Applications/Hopet.app

首次启动时 App 会自动给所有识别到的 AI 工具（Claude Code、Codex CLI）安装 hooks，并把 hopet-emit helper 复制到 ~/.hopet/bin/。Merge 是非破坏性的——~/.claude/settings.json 与 ~/.codex/hooks.json 里已有的 hook 都会保留。后续启动检测到已安装则直接跳过。

偏好面板的 Hooks Tab 用来查看安装状态、跑诊断 Doctor、以及给每个工具单独做 listener 软静音（不动 hook 文件，仅在 EventRouter 入口丢事件）。

想换一只自己的宠物，进 Themes Tab，点 Import Theme…。你可以填一个名字并准备好对应的 8 张动画 GIF，也可以直接选择 Codex pet 格式的文件夹或 ZIP 包（内含 pet.json 与 spritesheet.png / spritesheet.webp）；主题会落在 ~/.hopet/themes/<id>/，与内置 Hopi 并列。

从源码构建

环境要求：macOS 14+，Swift 5.10+（Command Line Tools 即可）。

swift run Hopet                  # 编译并启动
swift build                      # 只编译，不启动
swift run hopet-emit --help      # 查看 CLI helper 支持的 flag

架构与协议

• DevDocs/architecture.md——状态机、聚合器、IPC 帧格式与模块边界
• DevDocs/features.md——功能清单与 UI 行为的详细说明
• DevDocs/hooks-and-priority.md——hook 事件 schema 与优先级解析
• DevDocs/preferences.md——偏好项键值与主题导入契约

友情链接

• LINUX DO

许可

本项目以 MIT License 发布。© 2026 BinaryFroggy。