cc-pets 2.1.0 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CC_BRIDGE.md +11 -6
  2. package/CC_BRIDGE.zh-CN.md +8 -4
  3. package/CHANGELOG.md +59 -1
  4. package/CHANGELOG.zh-CN.md +59 -1
  5. package/README.md +60 -12
  6. package/README.zh-CN.md +58 -13
  7. package/Sources/CCPets/CCPetsAppDelegate+AgentEvents.m +215 -0
  8. package/Sources/CCPets/CCPetsAppDelegate+AgentStatus.m +660 -0
  9. package/Sources/CCPets/CCPetsAppDelegate+Bridge.m +297 -0
  10. package/Sources/CCPets/CCPetsAppDelegate+Pets.m +187 -0
  11. package/Sources/CCPets/CCPetsAppDelegate+Private.h +322 -0
  12. package/Sources/CCPets/CCPetsAppDelegate+Quota.m +216 -0
  13. package/Sources/CCPets/CCPetsAppDelegate+Settings.m +205 -0
  14. package/Sources/CCPets/CCPetsAppDelegate+Speech.m +392 -0
  15. package/Sources/CCPets/CCPetsAppDelegate+Update.m +458 -0
  16. package/Sources/CCPets/CCPetsAppDelegate.h +17 -16
  17. package/Sources/CCPets/CCPetsAppDelegate.m +74 -2406
  18. package/Sources/CCPets/CCPetsCleanup.h +4 -0
  19. package/Sources/CCPets/CCPetsCleanup.m +35 -2
  20. package/Sources/CCPets/CCPetsCodexRateLimits.h +1 -0
  21. package/Sources/CCPets/CCPetsCodexRateLimits.m +7 -0
  22. package/Sources/CCPets/CCPetsEvents.m +1 -1
  23. package/Sources/CCPets/CCPetsGlassMenu.h +10 -0
  24. package/Sources/CCPets/CCPetsGlassMenu.m +196 -0
  25. package/Sources/CCPets/CCPetsGlassView.h +31 -0
  26. package/Sources/CCPets/CCPetsGlassView.m +246 -0
  27. package/Sources/CCPets/CCPetsPaths.h +7 -1
  28. package/Sources/CCPets/CCPetsPaths.m +14 -1
  29. package/Sources/CCPets/CCPetsTerminalFocus.h +15 -0
  30. package/Sources/CCPets/CCPetsTerminalFocus.m +306 -15
  31. package/Sources/CCPets/CCPetsUsage.h +2 -1
  32. package/Sources/CCPets/CCPetsUsage.m +69 -21
  33. package/Sources/CCPets/CCPetsUsageMonitor.m +43 -8
  34. package/Sources/CCPets/CCPetsVersion.h +7 -0
  35. package/Sources/CCPets/CCPetsVersion.m +82 -0
  36. package/Sources/CCPets/MenuChoiceRow.h +19 -0
  37. package/Sources/CCPets/MenuChoiceRow.m +96 -0
  38. package/Sources/CCPets/MenuHintView.h +15 -0
  39. package/Sources/CCPets/MenuHintView.m +128 -0
  40. package/Sources/CCPets/PetView.h +2 -0
  41. package/Sources/CCPets/PetView.m +121 -53
  42. package/Sources/CCPets/QuotaDashboardView.h +3 -4
  43. package/Sources/CCPets/QuotaDashboardView.m +222 -146
  44. package/Sources/CCPets/main.m +29 -0
  45. package/bin/cc-pets +39 -1
  46. package/bin/codex-with-pet +2 -0
  47. package/package.json +3 -2
  48. package/scripts/bridge/cli.mjs +9 -2
  49. package/scripts/bridge/core.mjs +1 -1
  50. package/scripts/bridge/install.mjs +23 -1
  51. package/scripts/bridge/process.mjs +22 -0
  52. package/scripts/doctor.mjs +456 -0
  53. package/scripts/install-claude-hooks.mjs +12 -18
  54. package/scripts/install-codex-hooks.mjs +3 -9
  55. package/scripts/integration-markers.mjs +51 -0
  56. package/scripts/pet-store.mjs +2 -1
  57. package/scripts/uninstall-integrations.mjs +16 -44
  58. package/scripts/uninstall-shell-integration.sh +3 -3
package/CC_BRIDGE.md CHANGED
@@ -188,6 +188,11 @@ The Claude Code watcher arms at session start and at the end of every turn, and
188
188
  inbox and are included with the user's next prompt; messages that arrive during that turn are
189
189
  delivered when it ends.
190
190
 
191
+ Waking Codex requires a Codex version with the `codex queue` subcommand. `cc-pets bridge enable`,
192
+ `cc-pets bridge status`, and `cc-pets doctor` check the installed version. Without it, CC Bridge
193
+ still works: messages to Codex wait in its inbox until it calls `check_inbox` or the user's next
194
+ prompt brings them in.
195
+
191
196
  Senders get receipts such as "queued", "in inbox", or "undeliverable". Delivery does not mean
192
197
  the recipient has read or agreed to anything.
193
198
 
@@ -212,15 +217,15 @@ Right-click the pet → **CC Bridge**:
212
217
  | Switch | Effect |
213
218
  | --- | --- |
214
219
  | 启用 (Enable) | Same as `cc-pets bridge enable / disable`; takes a few seconds |
215
- | 免审批 (Skip approval): 查看类 view / 发消息 send / 文件预留 reserve / 改会话名 rename | Each group applies to both Codex approval and Claude permissions. With "send" on, agents can message other sessions without asking |
216
220
  | 自动唤醒 (Auto-wake) | Same as `--wake` |
217
221
  | 编辑拦截 (Edit guard) | Same as `--edit-guard` |
218
- | 消息角标 (Message badge) | Pet only: show the message badge on the status icon |
219
- | 新消息通知 (New-message notifications) | Pet only: a system notification when sessions message each other (sender and recipient only, never the body); asks for notification permission the first time |
222
+ | 免审批 (Skip approval) › 查看类 view / 发消息 send / 文件预留 reserve / 改会话名 rename | Each group applies to both Codex approval and Claude permissions. With "send" on, agents can message other sessions without asking |
223
+ | 桌宠提醒 (Pet alerts) › 消息角标 (Message badge) | Pet only: show the message badge on the status icon |
224
+ | 桌宠提醒 (Pet alerts) › 新消息通知 (New-message notifications) | Pet only: a system notification when sessions message each other (sender and recipient only, never the body); asks for notification permission the first time |
220
225
 
221
- The pet's UI is currently in Simplified Chinese. The bottom of the menu shows "N 会话 · M 预留"
222
- (online sessions and active reservations), and each switch has a hover tooltip. Except for the badge and
223
- notification switches, everything is dimmed while CC Bridge is off. The menu finds the command-line
226
+ The pet's UI is currently in Simplified Chinese. "N 会话 · M 预留" (online sessions and active
227
+ reservations) appears under 启用, and each switch has a hover tooltip. While CC Bridge is off the menu
228
+ shows only 启用; reopen the menu after enabling to see the other switches. The menu finds the command-line
224
229
  tool through `~/.cc-pets/bridge-cli.json`, written on every `cc-pets install`; if it's missing, you'll be asked to reinstall.
225
230
 
226
231
  ## Security and privacy
@@ -167,6 +167,10 @@ Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多
167
167
  如果 Claude 会话在这段空窗期里一直空闲,消息会留在信箱,等用户下次输入时一并带入;
168
168
  那一轮进行中新到的消息,在该轮结束时投递。
169
169
 
170
+ 自动唤醒 Codex 需要支持 `codex queue` 子命令的 Codex 版本。`cc-pets bridge enable`、
171
+ `cc-pets bridge status` 与 `cc-pets doctor` 会检测当前版本;不支持时 CC Bridge 仍可使用,
172
+ 发给 Codex 的消息会先进信箱,由对方调用 `check_inbox` 或在下次输入时带入。
173
+
170
174
  发送方只会收到"已送达队列 / 已放入信箱 / 无法投递"这类回执。送达不代表对方已读,也不代表对方同意。
171
175
 
172
176
  ## 桌宠里的显示
@@ -187,13 +191,13 @@ Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多
187
191
  | 开关 | 作用 |
188
192
  | --- | --- |
189
193
  | 启用 | 等同 `cc-pets bridge enable / disable`,执行需要几秒 |
190
- | 免审批:查看类 / 发消息 / 文件预留 / 改会话名 | 每组同时作用于 Codex 免审批与 Claude 免确认。"发消息"开启后,Agent 可以不经确认给其他会话发消息 |
191
194
  | 自动唤醒 | 自动唤醒空闲会话,同 `--wake` |
192
195
  | 编辑拦截 | 编辑前预留拦截,同 `--edit-guard` |
193
- | 消息角标 | 只影响桌宠:是否显示状态图标右下角的消息角标 |
194
- | 新消息通知 | 只影响桌宠:会话之间有消息送达时发系统通知(只含谁发给谁,不含正文),首次开启时申请通知权限 |
196
+ | 免审批 › 查看类 / 发消息 / 文件预留 / 改会话名 | 每组同时作用于 Codex 免审批与 Claude 免确认。"发消息"开启后,Agent 可以不经确认给其他会话发消息 |
197
+ | 桌宠提醒 › 消息角标 | 只影响桌宠:是否显示状态图标右下角的消息角标 |
198
+ | 桌宠提醒 › 新消息通知 | 只影响桌宠:会话之间有消息送达时发系统通知(只含谁发给谁,不含正文),首次开启时申请通知权限 |
195
199
 
196
- 菜单底部显示"N 会话 · M 预留"(在线会话数与有效预留数),各开关悬停可看说明。除角标和通知外,其余开关在 CC Bridge 未开启时置灰。
200
+ "启用"下方显示"N 会话 · M 预留"(在线会话数与有效预留数),各开关悬停可看说明。CC Bridge 未开启时菜单里只有"启用"一项,开启后重新打开菜单即可看到其余开关。
197
201
  菜单开关通过 `~/.cc-pets/bridge-cli.json` 找到命令行程序(每次 `cc-pets install` 时写入);找不到时会提示重新安装。
198
202
 
199
203
  ## 安全与隐私
package/CHANGELOG.md CHANGED
@@ -5,7 +5,61 @@ English | [简体中文](./CHANGELOG.zh-CN.md)
5
5
  This project follows Semantic Versioning. `package.json` is the single source of
6
6
  truth for the version.
7
7
 
8
- ## [Unreleased]
8
+ ## [2.1.2] - 2026-10-04
9
+
10
+ Update prompts through the pet, `cc-pets doctor` and `cc-pets paths`, plus cleanup fixes.
11
+
12
+ ### Updates
13
+
14
+ - Check npm for a newer version 5 seconds after launch, and again when a CLI reopens a running pet (at most once every 10 minutes); failed checks stay silent.
15
+ - Announce a new version with a clickable speech bubble that shows up to three highlights from the matching GitHub Release. The bubble waits while an agent is busy, and with chatter on, idle speech now and then reminds you until you choose **Later**.
16
+ - Added a glass "↑" badge on the pet as a lasting entry point, and while a new version is available the right-click menu shows **Update to x.y.z…** at the top level; the update dialog lists highlights and links to the full release notes, and **About CC Pets** uses the same dialog style.
17
+ - **Check for Updates…** and **About CC Pets** moved into a new **Help** submenu.
18
+
19
+ ### CLI
20
+
21
+ - Added `cc-pets doctor`, a read-only check of the installation: Node.js, matching versions of the npm package, native binary and installed app, Claude Code and Codex hooks (including hooks that still point to a moved package), the Claude status line, shell shims and `PATH` order, the real CLI binaries, the updater config, and CC Bridge. Each problem comes with a fix, and the output shows the home directory as `~` so it can be pasted into an issue.
22
+ - Added `cc-pets paths [--json]`, which lists where settings, pet assets, phrases, caches and runtime state live, how large each is, and what `clean` and `--purge` remove.
23
+ - `cc-pets clean` now also removes the pet store manifest cache in `~/.cc-pets/cache`.
24
+ - `cc-pets uninstall --purge` keeps your pet assets and phrases in `~/.cc-pets`, as it always did; the help text, confirmation prompt and README now say so instead of promising to remove all local data.
25
+
26
+ ### CC Bridge
27
+
28
+ - `cc-pets bridge enable`, `cc-pets bridge status` and `cc-pets doctor` check whether the installed Codex supports `codex queue`. Without it, CC Bridge still turns on and messages to Codex wait in its inbox; upgrading Codex enables wake-up without re-enabling CC Bridge.
29
+
30
+ ## [2.1.1] - 2026-09-30
31
+
32
+ Feature release: the native Liquid Glass panel theme and multi-terminal jump-back, plus quota fixes.
33
+
34
+ ### Panels and menus
35
+
36
+ - Added a Liquid Glass panel theme on macOS 26 and later, chosen under **Panel theme** in the right-click menu; Classic stays the default and is unchanged. It covers the quota panel, status card, speech bubble and agent session list.
37
+ - The public glass styles turn frosted whenever the app is inactive, and the pet never activates. On macOS 27 an undocumented glass variant keeps the clear, refractive look; `defaults write com.universewang.cc-pets CCPetsDisableExperimentalGlass -bool YES` turns it off and falls back to public Clear glass.
38
+ - **Glass dimming** offers Clear (0%), Light (15%), Standard (25%, default) and Legible (45%); soft shades on the top and bottom edges tone down the bright rim.
39
+ - In Liquid Glass the quota panel uses white text with colored dots instead of colored text and pill badges, a minimum text size, monospaced digits and a light scrim under each card.
40
+ - The agent session list opens as a glass panel with a height limit and scrolling; unlike the system menu it has no arrow-key navigation.
41
+ - Theme and dimming choices apply immediately and keep the menu open, so levels can be compared.
42
+ - Added **About CC Pets** to the right-click menu.
43
+ - Menu switch hints now show even while the pet app is inactive.
44
+ - Removed the **Refresh usage** menu item and the quota panel's refresh button; usage still refreshes on a timer.
45
+ - The CC Bridge submenu is down from 14 rows to 6; while CC Bridge is off it shows only **Enable**.
46
+
47
+ ### Agent status
48
+
49
+ - Fix Codex bubbles jumping to the wrong terminal: Codex 0.159 runs every terminal's sessions in one shared `codex app-server --managed-daemon`, so hooks inherited the environment of whichever terminal started it. `codex-with-pet` now registers each launch, hooks pair new sessions with the launch in the same directory, and when no pairing is certain the bubble does not jump. Codex sessions started before this version need to be restarted once.
50
+
51
+ ### Quota and usage
52
+
53
+ - Fix idle Claude sessions rolling the quota back to an older, higher remaining value: a lower value is accepted only from a newer response, and expired 5-hour windows no longer show their old percentage.
54
+ - Keep the live Codex quota across restarts and app-server gaps, instead of falling back to an hours-old session-log snapshot.
55
+
56
+ ### CLI
57
+
58
+ - Added `cc-pets --help`; unknown flags now fail with exit status 2 instead of launching the pet, and `cc-pets uninstall --purge` takes effect.
59
+
60
+ ## [2.1.0] - 2026-09-24
61
+
62
+ CC Bridge for messaging between Claude Code and Codex sessions.
9
63
 
10
64
  ### CC Bridge (experimental, off by default)
11
65
 
@@ -18,6 +72,10 @@ truth for the version.
18
72
  - Options and pet switches: `cc-pets bridge configure` and `enable` accept `--approve` / `--codex-approve` / `--claude-allow` (skip approval in Codex and Claude by tool group), `--wake`, and `--edit-guard`, keeping anything not given; the pet's right-click menu gains a CC Bridge section (enable, four approval groups, auto-wake, edit guard, message badge, new-message notifications).
19
73
  - Custom session names via `CC_BRIDGE_NAME` at launch, or `set_name` / `cc-pets bridge name` in a session; `list_agents` shows each session's terminal (tty).
20
74
 
75
+ ### Agent status
76
+
77
+ - Fix the status card not jumping back from VS Code family editors: `TERM_PROGRAM=vscode` is shared by VS Code, Cursor, Windsurf and Antigravity, so it no longer decides the application on its own — the captured bundle identifier goes first, and every candidate that is not running is skipped instead of failing the whole jump.
78
+
21
79
  ## [2.0.3] - 2026-09-17
22
80
 
23
81
  Terminal jump-back and session-liveness fixes for agents started outside the wrapper scripts.
@@ -4,7 +4,61 @@
4
4
 
5
5
  本项目遵循语义化版本号。版本号以 `package.json` 为唯一来源。
6
6
 
7
- ## [未发布]
7
+ ## [2.1.2] - 2026-10-04
8
+
9
+ 桌宠提示新版本,新增 `cc-pets doctor` 与 `cc-pets paths`,以及清理相关修复。
10
+
11
+ ### 更新
12
+
13
+ - 启动 5 秒后到 npm 检查新版本,CLI 再次唤起已运行的桌宠时也会检查(最多每 10 分钟一次);检查失败不打扰。
14
+ - 发现新版本时桌宠弹出可点击的气泡,附上对应 GitHub Release 中最多三条要点。Agent 忙碌时气泡会等待;开启碎碎念时,空闲台词会不时提醒,直到选择「稍后」。
15
+ - 桌宠上新增玻璃「↑」角标作为常驻入口;有新版本时,右键菜单顶层临时出现「更新到 x.y.z…」。更新对话框列出要点并可打开完整说明,「关于 CC Pets」改用同样的对话框样式。
16
+ - 「检查更新…」与「关于 CC Pets」收进右键菜单新增的「帮助」子菜单。
17
+
18
+ ### 命令行
19
+
20
+ - 新增 `cc-pets doctor`:只读检查安装状态,包括 Node.js、npm 包 / 原生程序 / 已安装 App 的版本是否一致、Claude Code 与 Codex Hooks(含包被移动后仍指向旧位置的 Hooks)、Claude status line、shell shim 与 `PATH` 顺序、真实 CLI、自动更新配置和 CC Bridge。每个问题都给出修复命令;home 目录显示为 `~`,输出可直接贴进 issue。
21
+ - 新增 `cc-pets paths [--json]`:列出偏好、桌宠素材、台词、缓存与运行时状态的存放位置和大小,并注明 `clean` 与 `--purge` 各自会删除哪些。
22
+ - `cc-pets clean` 现在也会清理 `~/.cc-pets/cache` 中的素材清单缓存。
23
+ - `cc-pets uninstall --purge` 一直会保留 `~/.cc-pets` 中的桌宠素材与台词;帮助、确认提示和 README 现已如实说明,不再写"删除全部本地数据"。
24
+
25
+ ### CC Bridge
26
+
27
+ - `cc-pets bridge enable`、`cc-pets bridge status` 与 `cc-pets doctor` 会检测当前 Codex 是否支持 `codex queue`。不支持时 CC Bridge 仍可开启,发给 Codex 的消息先进信箱;升级 Codex 后即可自动唤醒,无需重新开启。
28
+
29
+ ## [2.1.1] - 2026-09-30
30
+
31
+ 功能版本:原生 Liquid Glass 面板主题与多终端跳转,以及额度修复。
32
+
33
+ ### 面板与菜单
34
+
35
+ - 新增 Liquid Glass 面板主题(macOS 26 及以上),在右键菜单「面板主题」里切换;默认仍是经典主题,经典主题不变。作用于额度面板、状态卡、说话气泡和 Agent 会话列表。
36
+ - 公开的玻璃样式在 App 未激活时会变成磨砂,而桌宠从不激活。macOS 27 上改用一个未公开的玻璃样式,保持清透和折射;执行 `defaults write com.universewang.cc-pets CCPetsDisableExperimentalGlass -bool YES` 可关闭,回退到公开的 Clear 玻璃。
37
+ - 「玻璃压暗」提供通透(0%)、轻度(15%)、标准(25%,默认)、清晰(45%)四档;玻璃上下沿加了柔和暗带,压住过亮的边缘高光。
38
+ - Liquid Glass 下额度面板改为白字加彩色圆点,不再使用彩色字和彩色底标签;小字设了字号下限,数字用等宽字形,卡片下垫一层浅衬底。
39
+ - Agent 会话列表改为玻璃面板,有高度上限,超出可滚动;与系统菜单不同,不支持方向键选择。
40
+ - 主题和压暗档位点击后立即生效,菜单不收起,方便连续对比。
41
+ - 右键菜单新增「关于 CC Pets」。
42
+ - 菜单开关的悬停说明在桌宠未激活时也能显示。
43
+ - 移除右键菜单的「刷新用量」和额度面板的刷新按钮;用量仍定时自动刷新。
44
+ - CC Bridge 子菜单从 14 行精简到 6 行;未启用时只显示「启用」。
45
+
46
+ ### Agent 状态
47
+
48
+ - 修复 Codex 气泡跳错终端:Codex 0.159 把所有终端的会话放进同一个 `codex app-server --managed-daemon` 执行,hook 继承的是最先拉起它的终端的环境。现在 `codex-with-pet` 会登记每次启动,hook 按同一工作目录把新会话配到对应的启动记录;配不准时气泡不跳转。本版本之前启动的 Codex 会话需要重启一次。
49
+
50
+ ### 额度与用量
51
+
52
+ - 修复空闲的 Claude 会话把额度回退到更早、更高的剩余值:只有更新的响应才能把数值调低,已过期的 5 小时窗口不再显示旧百分比。
53
+ - Codex 的实时额度在重启和 app-server 中断期间也能保留,不再回退到几小时前的会话日志快照。
54
+
55
+ ### 命令行
56
+
57
+ - 新增 `cc-pets --help`;未知参数改为以退出码 2 报错,不再启动桌宠;`cc-pets uninstall --purge` 现在生效。
58
+
59
+ ## [2.1.0] - 2026-09-24
60
+
61
+ CC Bridge:Claude Code 与 Codex 会话之间互发消息。
8
62
 
9
63
  ### CC Bridge(实验性,默认关闭)
10
64
 
@@ -17,6 +71,10 @@
17
71
  - 选项与菜单开关:`cc-pets bridge configure` 与 `enable` 支持 `--approve` / `--codex-approve` / `--claude-allow`(按分组放开 Codex 免审批与 Claude 免确认)、`--wake`、`--edit-guard`,未给出的选项保持原值;桌宠右键菜单新增 CC Bridge 开关组(启用、免审批四组、自动唤醒、编辑拦截、消息角标、新消息系统通知)。
18
72
  - 会话名可自定义:启动时用 `CC_BRIDGE_NAME`,或会话内调用 `set_name` / `cc-pets bridge name`;`list_agents` 显示会话所在终端(tty)。
19
73
 
74
+ ### Agent 状态
75
+
76
+ - 修复在 VS Code 家族编辑器里点状态卡片无法回跳:`TERM_PROGRAM=vscode` 是 VS Code、Cursor、Windsurf、Antigravity 共用的标记,不再由它单独决定跳转的应用——捕获到的 bundle ID 优先,候选里没在运行的直接跳过,不再让整次回跳失败。
77
+
20
78
  ## [2.0.3] - 2026-09-17
21
79
 
22
80
  修复未经包装脚本启动的 Agent 的终端回跳与会话存活判定。
package/README.md CHANGED
@@ -1,22 +1,52 @@
1
+ <p align="center">
2
+ <img src="docs/images/cover.png" alt="CC Pets v2.1.1: Liquid Glass theme and multi-terminal jump-back">
3
+ </p>
4
+
1
5
  # CC Pets
2
6
 
3
7
  English | [简体中文](./README.zh-CN.md)
4
8
 
5
- A native macOS desktop pet for Codex CLI and Claude Code CLI. CC Pets runs without
6
- either desktop app and reads five-hour and weekly quota data from local Codex
7
- sessions and Claude Code's official status line input.
9
+ A native macOS desktop pet for Codex CLI and Claude Code CLI that needs neither
10
+ desktop app. Launch CC Pets directly, or let it appear automatically when Codex CLI
11
+ or Claude Code CLI starts. It reads five-hour and weekly quota data from the official
12
+ Codex App Server interface and Claude Code's official status line input.
8
13
 
9
14
  > The application UI and the screenshots below are currently in Simplified Chinese.
10
- > English UI localization and English screenshots are planned for v2.1.0.
15
+ > English UI localization and English screenshots are planned for a future release.
16
+
17
+ ## What's new in v2.1.2
18
+
19
+ - **Update prompts from the pet** — CC Pets checks npm for a newer version shortly after
20
+ launch. When one is available, the pet shows a clickable speech bubble with up to three
21
+ highlights from the GitHub Release, and the bubble waits while an agent is busy. A glass
22
+ "↑" badge on the pet and an **Update to x.y.z…** item at the top of the right-click menu
23
+ open the update dialog. **Check for Updates…** and **About CC Pets** now live under a new
24
+ **Help** submenu.
25
+ - **`cc-pets doctor`** — read-only checks of versions, Claude Code and Codex hooks, the
26
+ status line, shims and `PATH`, the updater and CC Bridge, with a fix for each problem.
27
+ The output shows your home directory as `~`, so you can paste it into an issue.
28
+ - **`cc-pets paths`** — lists where settings, pet assets, phrases, caches and runtime
29
+ state live, how large each is, and what `clean` and `uninstall --purge` remove
30
+ (`--json` for machine-readable output).
31
+ - **Fixes** — `cc-pets clean` also clears the pet store manifest cache, and CC Bridge now
32
+ tells you when the installed Codex lacks `codex queue`, in which case messages to Codex
33
+ wait in its inbox.
34
+
35
+ See the [changelog](./CHANGELOG.md) for the full list.
11
36
 
12
37
  ## Screenshots
13
38
 
14
- | Subscription view | API usage view |
15
- | --- | --- |
16
- | ![Subscription view in the current Simplified Chinese UI](docs/images/subscription-mode.png) | ![API usage view in the current Simplified Chinese UI](docs/images/api-mode.png) |
39
+ <p align="center">
40
+ <img src="docs/images/liquid-glass-panel.png" width="80%" alt="Quota panel, speech bubble and pet in the Liquid Glass theme, current Simplified Chinese UI">
41
+ </p>
42
+
43
+ <p align="center">
44
+ <img src="docs/images/liquid-glass-menu.png" width="80%" alt="Right-click menu with the Panel theme submenu, current Simplified Chinese UI">
45
+ </p>
17
46
 
18
47
  ## Features
19
48
 
49
+ - Offers Classic and native Liquid Glass panel themes on macOS 26 and later.
20
50
  - Starts with Codex CLI or Claude Code CLI and closes after the last managed CLI exits.
21
51
  - Shares one pet across multiple simultaneous Codex and Claude sessions.
22
52
  - Shows five-hour and weekly remaining quota, reset times, local token totals, and seven-day trends.
@@ -27,6 +57,7 @@ sessions and Claude Code's official status line input.
27
57
  - Lists up to eight recent online Agent terminal sessions from the status card icon.
28
58
  - Badges the status icon with the number of sessions waiting for approval and pins those sessions to the top of the list.
29
59
  - Speaks up when an Agent sits in approval or thinking longer than its threshold.
60
+ - Announces new versions through the pet with release highlights and updates from the right-click menu.
30
61
  - Supports optional local quota history and macOS notifications.
31
62
  - Supports third-party CLI agents through a provider event protocol.
32
63
  - Includes editable global and per-pet speech.
@@ -125,18 +156,21 @@ cc-pets --version # Print the installed version.
125
156
  cc-pets --status # Print parsed Codex quota data.
126
157
  cc-pets --history # Print local quota history as JSON.
127
158
  cc-pets clean # Remove rebuildable state and caches.
159
+ cc-pets doctor # Check the installation and integrations, with fixes.
160
+ cc-pets paths # List where settings, caches and data are stored.
128
161
 
129
162
  cc-pets pet search otter # Search the configured asset source.
130
163
  cc-pets pet add boba # Install an asset into CC Pets' own directory.
131
164
  cc-pets pet list # List installed assets.
132
165
  cc-pets pet remove boba # Remove an installed asset.
133
166
 
167
+ cc-pets --help # List all commands.
134
168
  cc-pets install # Repair or reinitialize integrations.
135
169
  cc-pets bridge enable # CC Bridge (experimental, off by default); see CC_BRIDGE.md.
136
170
  cc-pets bridge status # Show CC Bridge state and online sessions.
137
171
  cc-pets bridge disable # Remove CC Bridge integrations.
138
172
  cc-pets uninstall # Remove integrations and restore the status line.
139
- cc-pets uninstall --purge # Also remove the app and all local data after confirmation.
173
+ cc-pets uninstall --purge # Also remove the app, app data and preferences after confirmation; keeps assets and phrases in ~/.cc-pets.
140
174
  cc-pets uninstall-app # Remove only ~/Applications/CC Pets.app.
141
175
 
142
176
  codex-with-pet # Start the pet and enter Codex CLI.
@@ -178,7 +212,16 @@ prompts, command text, file contents, or model output.
178
212
  | Hover on either body side | Directional interaction animation |
179
213
  | Click | Playful response animation |
180
214
  | Drag left or right | Directional drag animation |
181
- | Right-click | Pet, quota, notification, update, and exit menu |
215
+ | Right-click | Pet, notification, Help (update check and About), and exit menu |
216
+
217
+ The **Panel theme** submenu offers **Classic** and **Liquid Glass**. Classic is the
218
+ default. Changes apply immediately to the quota panel, status card, and speech
219
+ bubble, and persist across restarts. Liquid Glass uses native system glass and is
220
+ available on macOS 26 and later only. Building native glass support requires the
221
+ macOS 26 SDK or later. The same submenu has a **Glass dimming** setting for the quota
222
+ panel, status card, and speech bubble: Clear (0%), Light (15%), Standard (25%,
223
+ default), or Legible (45%). Lower levels
224
+ look more transparent; higher levels keep text readable over light backgrounds.
182
225
 
183
226
  The pet switcher scans only built-in assets and `~/.cc-pets/pets/`. It does not
184
227
  scan `~/.petdex/pets/` or `~/.codex/pets/`. To use assets installed by Codex,
@@ -201,8 +244,12 @@ add 16-direction mouse tracking while idle.
201
244
 
202
245
  ## Quota and local usage data
203
246
 
204
- Codex quota data comes from local `token_count` events under
205
- `~/.codex/sessions`. A `window_minutes` value of `300` is the five-hour window and
247
+ Codex quota data comes from the official Codex App Server interface. CC Pets starts
248
+ the installed Codex CLI as `codex app-server --stdio`, reads the current windows with
249
+ `account/rateLimits/read`, and follows `account/rateLimits/updated` notifications. The
250
+ server-side values replace the rate-limit snapshots recorded in local `token_count`
251
+ events under `~/.codex/sessions`; a local snapshot is used only when it is newer than
252
+ the last server value. A `window_minutes` value of `300` is the five-hour window and
206
253
  `10080` is the weekly window. CC Pets displays remaining percentage and does not
207
254
  substitute expired history when a current window is unavailable.
208
255
 
@@ -301,11 +348,12 @@ external assets.
301
348
 
302
349
  ## Privacy
303
350
 
304
- - Quota and token data are read from local Codex and Claude Code files.
351
+ - Codex quota is read through the official Codex App Server started from your installed Codex CLI with its existing sign-in; Claude quota comes from the status line input Claude Code passes locally. Token counts are read from local Codex and Claude Code files.
305
352
  - Hooks write only redacted state events and quota cache files to the current user's temporary directory.
306
353
  - Local quota history is disabled by default and retains seven days when enabled.
307
354
  - Status cards and notifications show only provider, state, and redacted tool category.
308
355
  - CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
356
+ - On launch, and when a CLI reopens the running pet, CC Pets asks the npm registry for the latest version (at most once every 10 minutes per run); only when a newer version exists does it read that version's release notes from the GitHub API. These requests carry no account or usage data.
309
357
  - Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
310
358
  - [CC Bridge](./CC_BRIDGE.md) is off by default. When enabled, messages between sessions are stored
311
359
  in the current user's temporary directory (owner-only, 24-hour expiry); it is the only feature
package/README.zh-CN.md CHANGED
@@ -1,18 +1,41 @@
1
+ <p align="center">
2
+ <img src="docs/images/cover.png" alt="CC Pets v2.1.1:Liquid Glass 主题与多终端回跳">
3
+ </p>
4
+
1
5
  # CC Pets
2
6
 
3
7
  [English](./README.md) | 简体中文
4
8
 
5
- 一个不依赖 Codex/Claude 桌面端的 macOS 原生桌宠。启动 Codex CLI 或 Claude Code CLI 时自动出现,
6
- 并从本机 `~/.codex/sessions` 与 Claude Code 官方 status line 数据中读取 5 小时额度、周额度和周重置时间。
9
+ 一个不依赖 Codex/Claude 桌面端的 macOS 原生桌宠。直接启动桌面端,或启动 Codex CLI / Claude Code CLI 时自动出现,
10
+ 并通过 Codex App Server 官方接口与 Claude Code 官方 status line 数据读取 5 小时额度、周额度和周重置时间。
7
11
 
8
- ## 展示模式
12
+ ## v2.1.2 新功能
9
13
 
10
- | 订阅展示模式 | API 调用展示模式 |
11
- | --- | --- |
12
- | ![订阅展示模式](docs/images/subscription-mode.png) | ![API 调用展示模式](docs/images/api-mode.png) |
14
+ - **桌宠提示新版本**:启动后不久自动到 npm 检查新版本。有新版本时,桌宠弹出可点击的气泡,附上
15
+ GitHub Release 中最多三条要点;Agent 忙碌时气泡会等待。桌宠上的玻璃「↑」角标和右键菜单顶层的
16
+ 「更新到 x.y.z…」都能直接打开更新对话框。「检查更新…」与「关于 CC Pets」收进新的「帮助」子菜单。
17
+ - **`cc-pets doctor`**:只读检查版本、Claude Code 与 Codex Hooks、status line、shim 与 `PATH`、
18
+ 自动更新和 CC Bridge,每个问题都附修复命令;home 目录显示为 `~`,输出可直接贴进 issue。
19
+ - **`cc-pets paths`**:列出偏好、桌宠素材、台词、缓存与运行时状态的位置和大小,并注明 `clean`
20
+ 与 `uninstall --purge` 各自删除哪些(`--json` 输出机器可读格式)。
21
+ - **修复**:`cc-pets clean` 会一并清理素材清单缓存;当前 Codex 不支持 `codex queue` 时,CC Bridge
22
+ 会明确提示,发给 Codex 的消息先进信箱。
23
+
24
+ 完整改动见 [更新记录](./CHANGELOG.zh-CN.md)。
25
+
26
+ ## 界面预览
27
+
28
+ <p align="center">
29
+ <img src="docs/images/liquid-glass-panel.png" width="80%" alt="Liquid Glass 主题下的额度面板、说话气泡与桌宠">
30
+ </p>
31
+
32
+ <p align="center">
33
+ <img src="docs/images/liquid-glass-menu.png" width="80%" alt="右键菜单中的面板主题子菜单">
34
+ </p>
13
35
 
14
36
  ## 功能
15
37
 
38
+ - macOS 26 及以上可在经典与原生 Liquid Glass 两种面板主题之间切换
16
39
  - 随 Codex CLI 或 Claude Code CLI 自动启动,无需打开对应桌面版
17
40
  - 多个 Codex/Claude CLI 共用一个桌宠,最后一个 CLI 退出后桌宠自动关闭
18
41
  - 鼠标悬停口袋时展开额度详情面板,用两张卡分别显示 Codex、Claude 的剩余 5 小时额度、周额度和精确到秒的周重置时间
@@ -20,7 +43,8 @@
20
43
  - 支持待机、左右拖动、身体两侧感应、头部/脚部悬停和点击反馈动画
21
44
  - 待机呼吸、随机小动作(11 行素材会转头看鼠标)、拖动时的水平滞后与落脚回弹
22
45
  - 桌宠以自己的口吻播报 Agent 状态,闲着时还会自己碎碎念,台词和频率都可自定义
23
- - 支持拖动桌宠位置,右键刷新用量、检查更新或退出
46
+ - 支持拖动桌宠位置,右键「帮助」中检查更新或查看关于;用量定时自动刷新
47
+ - 发现新版本时桌宠用气泡提醒并附上更新要点,点击即可打开更新对话框
24
48
  - 响应 Codex 与 Claude Code Agent 的思考、工具调用、审批、子 Agent、完成和失败状态
25
49
  - 在桌宠旁显示脱敏后的玻璃 Agent 状态卡片,可展开、折叠并显示活跃 CLI 会话数
26
50
  - 点击任意 Hook 状态卡,可返回触发该事件的终端;直接启动、没走包装脚本的会话同样可以回跳
@@ -83,7 +107,13 @@ JetBrains IDE、Warp、WezTerm、Ghostty 等在不安装扩展的模式下仅激
83
107
  | 按住并向右拖动 | 播放向右拖行动画,同时移动桌宠 |
84
108
  | 按住并向左拖动 | 播放向左拖行动画,同时移动桌宠 |
85
109
  | 鼠标移开或拖动结束 | 恢复默认待机动画 |
86
- | 右键桌宠 | 切换桌宠、刷新用量、设置历史/通知、检查更新或退出 |
110
+ | 右键桌宠 | 切换桌宠、设置历史/通知、在「帮助」中检查更新或查看关于、退出 |
111
+
112
+ 右键菜单「面板主题」提供「经典」和「Liquid Glass」,默认使用经典样式。
113
+ 选择后立即应用于额度面板、状态条和说话气泡,并在重启后保留。Liquid Glass 使用系统原生玻璃,
114
+ 仅在 macOS 26 及以上可选;构建原生玻璃支持需要 macOS 26 或更新的 SDK。同一子菜单里的「玻璃压暗」
115
+ 可在通透(0%)、轻度(15%)、标准(25%,默认)、清晰(45%)之间切换,作用于额度面板、状态卡和
116
+ 说话气泡:档位越低越通透,档位越高在浅色背景上越容易看清。
87
117
 
88
118
  右键菜单中的“切换桌宠”只扫描 `~/.cc-pets/pets/`(见 [素材管理](#素材管理))和包内素材,
89
119
  **不会**去读 `~/.petdex/pets/` 和 `~/.codex/pets/`——那两个目录由 PetDex CLI 和 Codex 写入,
@@ -332,7 +362,8 @@ npm 的安装后脚本会自动构建原生应用、安装两套 Agent Hooks,
332
362
  同时会将标准 macOS 应用安装到 `~/Applications/CC Pets.app`,可从 Finder 或 Launchpad 启动,
333
363
  不需要管理员权限。npm 升级时会同步更新该应用。
334
364
 
335
- 安装完成后也可以右键桌宠并选择“检查更新…”。应用会查询 npm Registry,发现新版本后请求确认,
365
+ 桌宠启动后会自动检查新版本,发现后用气泡提醒;也可以右键桌宠并选择「帮助 → 检查更新…」;已发现新版本时,右键菜单顶层会直接出现「更新到 x.y.z…」。
366
+ 应用会查询 npm Registry,发现新版本后请求确认,
336
367
  随后在后台复用首次安装时记录的 Node.js/npm 完成升级;用户无需打开终端。升级会同步更新原生应用、
337
368
  Codex/Claude Hooks 和 shell 集成,并自动重启正在运行的桌宠。自动更新不会请求管理员权限;如果原来的
338
369
  全局 npm 目录不可写或 Node.js/npm 已被移动,应用会保留旧版本并显示更新日志和手动升级命令。
@@ -375,9 +406,15 @@ cc-pets --status
375
406
  # 查看本机额度历史 JSON
376
407
  cc-pets --history
377
408
 
378
- # 清理可重建的临时状态、更新日志和构建缓存,保留历史、配置与偏好
409
+ # 清理可重建的临时状态、更新日志、素材清单缓存和构建缓存,保留历史、配置与偏好
379
410
  cc-pets clean
380
411
 
412
+ # 检查安装、Hooks、status line、shim 与 CC Bridge 是否正常,并给出修复建议;输出已脱敏,可直接贴进 issue
413
+ cc-pets doctor
414
+
415
+ # 列出偏好、桌宠素材、台词、缓存与运行时状态的存放位置和大小(--json 输出机器可读格式)
416
+ cc-pets paths
417
+
381
418
  # 管理 ~/.cc-pets/pets 里的桌宠素材,详见「素材与版权」
382
419
  cc-pets pet search otter
383
420
  cc-pets pet add boba
@@ -395,10 +432,13 @@ cc-pets bridge enable
395
432
  cc-pets bridge status
396
433
  cc-pets bridge disable
397
434
 
435
+ # 查看全部命令
436
+ cc-pets --help
437
+
398
438
  # 安全移除 Hooks、恢复 Claude status line,并清理 shell 集成
399
439
  cc-pets uninstall
400
440
 
401
- # 完整移除集成、应用和全部本地数据;执行前会再次确认
441
+ # 完整移除集成、应用、应用数据和偏好;执行前会再次确认。~/.cc-pets 下的桌宠素材与台词会保留
402
442
  cc-pets uninstall --purge
403
443
 
404
444
  # 仅删除 ~/Applications 中的 macOS 应用(不会删除 npm 包或 Hooks)
@@ -417,7 +457,11 @@ claude-with-pet
417
457
 
418
458
  ## 用量数据
419
459
 
420
- Codex 用量来自 `~/.codex/sessions` 的本地 `token_count` 事件:
460
+ Codex 额度来自 Codex App Server 官方接口:桌宠用本机已安装的 Codex CLI 启动
461
+ `codex app-server --stdio`,通过 `account/rateLimits/read` 读取当前额度窗口,并订阅
462
+ `account/rateLimits/updated` 推送。服务端返回的额度会覆盖 `~/.codex/sessions` 本地
463
+ `token_count` 事件里记录的额度快照;只有本地快照比最近一次服务端数据更新时才使用本地值。
464
+ 本地 Token 统计仍来自 `token_count` 事件:
421
465
 
422
466
  - `window_minutes = 300` 对应 5 小时额度
423
467
  - `window_minutes = 10080` 对应周额度
@@ -589,12 +633,13 @@ PetDex 官方 CLI(`npx petdex install <slug>`)会把素材放在 `~/.petdex/
589
633
 
590
634
  ## 隐私
591
635
 
592
- - Codex 额度与 Token 只从本机 `~/.codex/sessions` 读取(可用 `CC_PETS_CODEX_HOME` 覆盖)。
636
+ - Codex 额度通过本机 Codex CLI 启动的官方 App Server 读取,沿用 Codex CLI 自身的登录状态;Codex Token 只从本机 `~/.codex/sessions` 读取(可用 `CC_PETS_CODEX_HOME` 覆盖)。
593
637
  - Claude 额度只从 Claude Code 传给本机 status line 的 `rate_limits` 字段读取。
594
638
  - Agent Hooks 只向当前用户的临时目录写入桌宠事件和额度缓存。
595
639
  - 额度历史默认关闭;启用后只在本机保留最近 7 天的剩余比例快照。
596
640
  - 状态气泡和通知只显示 Provider、状态及脱敏工具类别,不显示会话正文。
597
641
  - 项目不上传会话内容、额度、凭据或使用统计,也不包含遥测服务。
642
+ - 桌宠启动时及 CLI 再次唤起桌宠时会向 npm Registry 查询最新版本号(同一次运行内最多每 10 分钟一次);仅在有新版本时再向 GitHub API 读取该版本的 Release 说明。请求不携带任何账号或使用数据。
598
643
  - 右键“退出桌宠”或执行 `cc-pets uninstall` 后,不会继续运行后台守护进程。
599
644
  - [CC Bridge](./CC_BRIDGE.zh-CN.md) 默认关闭;开启后,会话之间的消息正文会保存在当前用户的临时目录
600
645
  (仅本人可读,24 小时过期),这是本项目唯一会保存正文的功能。