Hopet

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 63 Open GitHub ↗

A macOS desktop AI pet that mirrors your Claude Code & Codex CLI session state in real time. 支持Claude Code和Codex CLI 的像素风AI桌面宠物，会话状态实时映射，支持导入自定义宠物素材。

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

简体中文 · <a href="./README.en.md">English</a>

<h1 align="center">Hopet</h1>

一只常驻 macOS 桌面的 AI 宠物，用动画和气泡显示
 <a href="https://claude.com/claude-code">Claude Code</a> /
 <a href="https://github.com/openai/codex">Codex CLI</a>
 正在思考、执行工具、等待确认、请求权限或完成任务，并通过桌面宠物与灵动岛提醒你关注 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 内实际播放的动画，按优先级从高到低排列。

<table width="100%">
 <tr>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-ask-user.gif" alt="Ask User" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-permission-prompt.gif" alt="Permission Prompt" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-error-interrupted.gif" alt="Error / Interrupted" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-tool-use.gif" alt="Tool Use" width="200" /></td>
 </tr>
 <tr>
 <td align="center" width="25%">Ask User</td>
 <td align="center" width="25%">Permission Prompt</td>
 <td align="center" width="25%">Error / Interrupted</td>
 <td align="center" width="25%">Tool Use</td>
 </tr>
 <tr>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-thinking.gif" alt="Thinking" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-responding.gif" alt="Responding" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-completed.gif" alt="Completed" width="200" /></td>
 <td align="center" width="25%"><img src="./DevDocs/assets/HopiGif/seal-idle.gif" alt="Idle" width="200" /></td>
 </tr>
 <tr>
 <td align="center" width="25%">Thinking</td>
 <td align="center" width="25%">Responding</td>
 <td align="center" width="25%">Completed</td>
 <td align="center" width="25%">Idle</td>
 </tr>
</table>

## 安装

环境要求：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/<id>/`，与内置 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/)

## 许可

Hopet

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README