简体中文 · 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//` 并写入 `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

Hopi permission prompt

## 安装环境要求：macOS 14+，Apple Silicon。当前发布的 v0.1.2 DMG 暂不提供 Intel 二进制；Intel Mac 可从源码构建。 1. 从 [Releases 页面](https://github.com/BinaryFroggy/Hopet/releases/latest) 下载 `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//`，与内置 Hopi 并列。 ## 从源码构建环境要求：macOS 14+，Swift 5.10+（Command Line Tools 即可）。 ```bash swift run Hopet # 编译并启动 swift build # 只编译，不启动 swift run hopet-emit --help # 查看 CLI helper 支持的 flag ``` ## 架构与协议 - [DevDocs/architecture.md](./DevDocs/architecture.md)——状态机、聚合器、IPC 帧格式与模块边界 - [DevDocs/features.md](./DevDocs/features.md)——功能清单与 UI 行为的详细说明 - [DevDocs/hooks-and-priority.md](./DevDocs/hooks-and-priority.md)——hook 事件 schema 与优先级解析 - [DevDocs/preferences.md](./DevDocs/preferences.md)——偏好项键值与主题导入契约 ## 友情链接 - [LINUX DO](https://linux.do/) ## 许可本项目以 [MIT License](./LICENSE) 发布。© 2026 BinaryFroggy。