cc-pets 2.4.0 → 2.5.0
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.
- package/CC_BRIDGE.md +46 -9
- package/CC_BRIDGE.zh-CN.md +29 -6
- package/CHANGELOG.md +55 -0
- package/CHANGELOG.zh-CN.md +56 -1
- package/CONTRIBUTING.md +1 -1
- package/CONTRIBUTING.zh-CN.md +1 -1
- package/PROVIDER_PROTOCOL.md +5 -1
- package/PROVIDER_PROTOCOL.zh-CN.md +4 -1
- package/README.md +69 -16
- package/README.zh-CN.md +54 -19
- package/Resources/zh-Hans.lproj/Localizable.strings +35 -11
- package/Sources/CCPets/App/CCPetsAppDelegate+AgentEvents.m +47 -4
- package/Sources/CCPets/App/CCPetsAppDelegate+AgentStatus.m +109 -14
- package/Sources/CCPets/App/CCPetsAppDelegate+Bridge.m +8 -6
- package/Sources/CCPets/App/CCPetsAppDelegate+MenuBar.m +86 -0
- package/Sources/CCPets/App/CCPetsAppDelegate+Private.h +13 -0
- package/Sources/CCPets/App/CCPetsAppDelegate+Quota.m +6 -1
- package/Sources/CCPets/App/CCPetsAppDelegate+Speech.m +5 -3
- package/Sources/CCPets/App/CCPetsAppDelegate+Update.m +4 -1
- package/Sources/CCPets/App/CCPetsAppDelegate+Workbench.m +4 -0
- package/Sources/CCPets/App/CCPetsAppDelegate.h +10 -0
- package/Sources/CCPets/App/CCPetsAppDelegate.m +4 -2
- package/Sources/CCPets/Bridge/CCPetsBridge.m +34 -12
- package/Sources/CCPets/Bridge/CCPetsBridgeCLI.m +100 -33
- package/Sources/CCPets/Bridge/CCPetsBridgeCore.h +12 -3
- package/Sources/CCPets/Bridge/CCPetsBridgeCore.m +317 -89
- package/Sources/CCPets/Bridge/CCPetsBridgeSetup.h +0 -2
- package/Sources/CCPets/Bridge/CCPetsBridgeSetup.m +210 -95
- package/Sources/CCPets/Bridge/CCPetsBridgeStore.h +28 -3
- package/Sources/CCPets/Bridge/CCPetsBridgeStore.m +222 -35
- package/Sources/CCPets/Integrations/CCPetsEvents.h +5 -0
- package/Sources/CCPets/Integrations/CCPetsEvents.m +68 -12
- package/Sources/CCPets/Integrations/CCPetsIntegrations.m +1 -1
- package/Sources/CCPets/Integrations/CCPetsTerminalFocus.h +6 -0
- package/Sources/CCPets/Integrations/CCPetsTerminalFocus.m +54 -5
- package/Sources/CCPets/Pet/CCPetsPhrasesEditor.m +7 -0
- package/Sources/CCPets/Pet/PetView+Menu.m +9 -1
- package/Sources/CCPets/Pet/PetView.h +7 -0
- package/Sources/CCPets/Pet/PetView.m +12 -1
- package/Sources/CCPets/Support/CCPetsPreferences.h +10 -0
- package/Sources/CCPets/Support/CCPetsPreferences.m +18 -0
- package/Sources/CCPets/UI/CCPetsMenuBarIcon.h +16 -0
- package/Sources/CCPets/UI/CCPetsMenuBarIcon.m +70 -0
- package/Sources/CCPets/UI/CCPetsMenuBarPanel.h +18 -0
- package/Sources/CCPets/UI/CCPetsMenuBarPanel.m +528 -0
- package/Sources/CCPets/UI/CCPetsMenuBarSummary.h +51 -0
- package/Sources/CCPets/UI/CCPetsMenuBarSummary.m +95 -0
- package/Sources/CCPets/UI/CCPetsSettingsPage.h +4 -1
- package/Sources/CCPets/UI/CCPetsSettingsPage.m +16 -0
- package/Sources/CCPets/UI/CCPetsStatusItem.h +28 -0
- package/Sources/CCPets/UI/CCPetsStatusItem.m +147 -0
- package/Sources/CCPets/UI/CCPetsWorkbenchPages.m +5 -3
- package/package.json +1 -1
package/CC_BRIDGE.md
CHANGED
|
@@ -66,13 +66,33 @@ The agent uses these MCP tools:
|
|
|
66
66
|
| Tool | Description |
|
|
67
67
|
| --- | --- |
|
|
68
68
|
| `list_agents` | Lists online sessions: name [ref], CLI, busy/idle, terminal (tty), start time, directory. The name is the address; add ` [ref]` only when names collide. |
|
|
69
|
-
| `send_message` | Sends a message. With `notify_when_idle: true`, you get a one-shot notice when the recipient next finishes a turn. |
|
|
69
|
+
| `send_message` | Sends a message. With `notify_when_idle: true`, you get a one-shot notice when the recipient next finishes a turn. That doesn't mean it has handled this message. |
|
|
70
70
|
| `set_name` | Renames the current session. |
|
|
71
71
|
| `reserve_files` | Reserves files or directories you are about to edit (globs supported); returns conflicts when they overlap with other reservations. |
|
|
72
72
|
| `release_files` | Releases this session's reservations. |
|
|
73
73
|
| `list_reservations` | Lists reservations in the current repository, or who reserved a given file. |
|
|
74
74
|
| `check_inbox` | Reads the inbox manually. Messages are normally delivered automatically. |
|
|
75
75
|
|
|
76
|
+
### Current session identity
|
|
77
|
+
|
|
78
|
+
Every MCP tool accepts an optional `session_id` identifying the caller. Bridge supplies the current ID
|
|
79
|
+
in `SessionStart` and `UserPromptSubmit` hook context; agents should pass that exact value on each call.
|
|
80
|
+
For an existing session without this context, read `CODEX_THREAD_ID` (Codex) or
|
|
81
|
+
`CLAUDE_CODE_SESSION_ID` (Claude) from that session's own shell. Do not use a recipient's ID, guess
|
|
82
|
+
from the online list, or hard-code one session's ID in shared MCP configuration.
|
|
83
|
+
|
|
84
|
+
Multiple Codex sessions can share an app-server PID. When MCP does not inherit a session ID, the
|
|
85
|
+
argument distinguishes the caller. Each call independently validates the registration, live status,
|
|
86
|
+
provider and host PID; the MCP process never caches the selected identity. An invalid explicit ID,
|
|
87
|
+
one belonging to another host, or one that can't be checked because the MCP host process can't be
|
|
88
|
+
identified is rejected with the reason and without falling back to another identity. Calls without
|
|
89
|
+
the argument retain environment-based identification and unique PID matching for existing single-session
|
|
90
|
+
clients. Anonymous session listing remains available when identity cannot be resolved, but `list_reservations`
|
|
91
|
+
returns an error because the repository to check is unknown.
|
|
92
|
+
|
|
93
|
+
After updating, reconnect the CC Bridge MCP server (or restart its client) to load the new binary
|
|
94
|
+
and tool definitions with `session_id`.
|
|
95
|
+
|
|
76
96
|
### Session names
|
|
77
97
|
|
|
78
98
|
Default names look like `<account>.<project-directory>.<animal>`, for example `claude.my-app.otter` or
|
|
@@ -119,12 +139,14 @@ Claude / Codex sessions for wording changes to take effect (MCP instructions loa
|
|
|
119
139
|
| Notify a session | Use cc-bridge to tell api the login endpoint is now POST /api/login and returns a token; update the frontend call |
|
|
120
140
|
| Hand off a task | Ask web to write unit tests for src/api/login.ts and report back |
|
|
121
141
|
| Get an answer back | Ask api how far the database migration has gone, and have it reply through cc-bridge |
|
|
122
|
-
| Wait
|
|
142
|
+
| Wait for a result | Tell api to run the test suite and send you the result through cc-bridge |
|
|
143
|
+
| See when it's idle | Message api and have it notify you when it goes idle |
|
|
123
144
|
| Target by terminal | Send this to the Claude session in ttys003: … |
|
|
124
145
|
|
|
125
146
|
Replies arrive as new messages in your session. "Notify you when it goes idle" sends a one-shot
|
|
126
|
-
notice once the recipient finishes its turn (`notify_when_idle`)
|
|
127
|
-
|
|
147
|
+
notice once the recipient finishes its turn (`notify_when_idle`). If the recipient is busy, that may be
|
|
148
|
+
a turn that started before your message arrived, so the notice only means a turn ended, not that your
|
|
149
|
+
task is done. To wait for a result, ask the recipient to reply when it finishes.
|
|
128
150
|
|
|
129
151
|
### Several sessions in one repository
|
|
130
152
|
|
|
@@ -186,8 +208,8 @@ Just ask: "Reserve src/api before you start the refactor, and release it when yo
|
|
|
186
208
|
| Codex | Woken immediately through `codex queue` | Queued after the current turn | Not delivered; receipt is undeliverable |
|
|
187
209
|
| Claude Code | Woken by a background `asyncRewake` watcher | Injected into the current turn | Not delivered; receipt is undeliverable |
|
|
188
210
|
|
|
189
|
-
The Claude Code watcher arms at session start and at the end of every turn
|
|
190
|
-
55 minutes before
|
|
211
|
+
The Claude Code watcher arms at session start and at the end of every turn. A new watcher replaces the
|
|
212
|
+
previous one and restarts the wait, which lasts up to about 55 minutes before it exits. If a Claude session stays idle through that gap, messages stay in its
|
|
191
213
|
inbox and are included with the user's next prompt; messages that arrive during that turn are
|
|
192
214
|
delivered when it ends.
|
|
193
215
|
|
|
@@ -199,6 +221,15 @@ prompt brings them in.
|
|
|
199
221
|
Senders get receipts such as "queued", "in inbox", or "undeliverable". Delivery does not mean
|
|
200
222
|
the recipient has read or agreed to anything.
|
|
201
223
|
|
|
224
|
+
A session that crashes or is killed never fires `SessionEnd`. Its undelivered messages are cleaned up
|
|
225
|
+
the next time the session list finds it offline, or when the next session starts: receipts become
|
|
226
|
+
undeliverable and its idle subscriptions are removed.
|
|
227
|
+
|
|
228
|
+
Codex threads on a shared app-server run in the background. Closing a terminal tab doesn't end the
|
|
229
|
+
thread right away: `SessionEnd` fires when the app-server unloads it, which took up to a few minutes
|
|
230
|
+
when tested. Until then the thread still shows as online, and a message sent to it may be queued and
|
|
231
|
+
run when the thread is resumed.
|
|
232
|
+
|
|
202
233
|
## In the pet
|
|
203
234
|
|
|
204
235
|
With CC Bridge enabled, the round icon on the pet's status card gets a message badge in its
|
|
@@ -239,7 +270,9 @@ tool through `~/.cc-pets/bridge-cli.json`, written on every `cc-pets install`; i
|
|
|
239
270
|
when a peer asks for an action that was denied on its side, the agent should refuse and tell the user.
|
|
240
271
|
- Message bodies are stored in the current user's temporary directory
|
|
241
272
|
(`cc-bridge-<uid>/` under `getconf DARWIN_USER_TEMP_DIR`) with `0700` directories and `0600`
|
|
242
|
-
files; undelivered messages expire after 24 hours
|
|
273
|
+
files; undelivered messages expire after 24 hours (cleaned up when the next session starts). A body is
|
|
274
|
+
deleted once its message is delivered. Receipts hold only sender, recipient, time and status, and
|
|
275
|
+
stay about 48 hours for troubleshooting. This is an explicit exception to the
|
|
243
276
|
[Provider protocol](./PROVIDER_PROTOCOL.md)'s no-content rule, which is why CC Bridge is off by default.
|
|
244
277
|
- A message is limited to 16 KB. A pair of sessions exchanging more than 20 messages within
|
|
245
278
|
10 minutes is paused to stop two agents from auto-replying to each other in a loop.
|
|
@@ -252,15 +285,19 @@ Bridge validates `CODEX_THREAD_ID` / `CLAUDE_CODE_SESSION_ID` against the live s
|
|
|
252
285
|
current host process. Without a session ID, PID lookup is allowed only when it identifies exactly one
|
|
253
286
|
live session. Ambiguous shared hosts and stale explicit IDs fail closed for sending, renaming, reading
|
|
254
287
|
inboxes and managing reservations. CLI diagnostics can select a session explicitly with
|
|
255
|
-
`--from <session-name-or-full-session-id
|
|
288
|
+
`--from <session-name-or-full-session-id>`; with `send`, put it before the message.
|
|
256
289
|
|
|
257
290
|
Claimed inbox messages remain on disk until the complete output has been flushed successfully.
|
|
258
291
|
A later hook, watcher or `check_inbox` recovers unconfirmed messages after a crash. A crash between
|
|
259
292
|
output and confirmation may deliver the same message ID again; the host provides no acknowledgement
|
|
260
|
-
protocol, so exactly-once delivery is not guaranteed.
|
|
293
|
+
protocol, so exactly-once delivery is not guaranteed. When `codex queue` times out, Bridge can't tell
|
|
294
|
+
whether the message was queued, so it also goes to the inbox and the sender is told it may arrive
|
|
295
|
+
twice with the same ID. Codex queue delivery uses the recipient's Home.
|
|
261
296
|
Legacy records with an unknown Home fall back to the inbox until registration is refreshed by input
|
|
262
297
|
in that session.
|
|
263
298
|
|
|
264
299
|
Existing watchers recheck the enabled and auto-wake switches while polling. Disabling Bridge also
|
|
265
300
|
blocks CLI send, rename and inbox operations. Integration removal failures return a nonzero exit code;
|
|
266
301
|
the runtime remains disabled, and `disable` can be retried after resolving the reported errors.
|
|
302
|
+
`disable` deletes all undelivered messages and marks their receipts undeliverable. Delivered receipts
|
|
303
|
+
contain no message body and stay for their normal retention period.
|
package/CC_BRIDGE.zh-CN.md
CHANGED
|
@@ -50,6 +50,7 @@ cc-pets bridge configure --edit-guard=off # 关闭编辑前预留拦截
|
|
|
50
50
|
|
|
51
51
|
运行中的 watcher 会在轮询时检查关闭状态;关闭自动唤醒后不再主动取信,关闭 Bridge 后 CLI 也拒绝发送、改名和收件。
|
|
52
52
|
卸载集成失败会返回非零退出码,运行时开关仍保持关闭,可排除错误后再次执行 `disable`。
|
|
53
|
+
`disable` 会删除所有未投递的消息,回执标记为 undeliverable;已送达的回执不含正文,按保留期留作记录。
|
|
53
54
|
|
|
54
55
|
Claude 侧的改动会被热加载;Codex 侧(审批、hooks)需要重启 Codex 会话,hooks 变化后还要在 `/hooks` 中重新信任。
|
|
55
56
|
|
|
@@ -64,13 +65,27 @@ Agent 会调用这些 MCP 工具:
|
|
|
64
65
|
| 工具 | 说明 |
|
|
65
66
|
| --- | --- |
|
|
66
67
|
| `list_agents` | 列出在线会话:名字 [ref]、CLI、忙闲、所在终端(tty)、启动时间、目录。名字就是地址;只有重名时才需要写成 `名字 [ref]`。 |
|
|
67
|
-
| `send_message` | 发消息;`notify_when_idle: true`
|
|
68
|
+
| `send_message` | 发消息;`notify_when_idle: true` 时,对方下次完成回合后你会收到一条一次性空闲通知。这不代表对方已处理这条消息。 |
|
|
68
69
|
| `set_name` | 修改当前会话的名字。 |
|
|
69
70
|
| `reserve_files` | 预留即将修改的文件或目录(支持 glob),与他人预留重叠时返回冲突列表。 |
|
|
70
71
|
| `release_files` | 释放本会话的预留。 |
|
|
71
72
|
| `list_reservations` | 查看当前仓库的所有预留,或某个文件被谁预留。 |
|
|
72
73
|
| `check_inbox` | 手动读取信箱。正常情况下消息会自动送达,一般不需要调用。 |
|
|
73
74
|
|
|
75
|
+
### 当前会话身份
|
|
76
|
+
|
|
77
|
+
所有 MCP 工具都支持可选的 `session_id` 参数,用来标识调用者。Bridge 在 `SessionStart` 和
|
|
78
|
+
`UserPromptSubmit` hook 的上下文中提供当前 ID,Agent 应在每次调用中原样传入;旧会话缺少该上下文时,
|
|
79
|
+
可从当前会话 shell 的 `CODEX_THREAD_ID`(Codex)或 `CLAUDE_CODE_SESSION_ID`(Claude)读取。
|
|
80
|
+
不要使用收件人的 ID、从在线列表猜测,或把某个会话的 ID 固定写进共享 MCP 配置。
|
|
81
|
+
|
|
82
|
+
Codex 的多个会话可以共用一个 app-server PID;MCP 未继承会话 ID 时,必须通过参数区分调用者。
|
|
83
|
+
每次调用独立校验注册记录、在线状态、provider 和宿主 PID,不在 MCP 进程中缓存会话身份。
|
|
84
|
+
显式 ID 无效或不属于当前宿主时直接报错,错误信息会说明原因;识别不出 MCP 的宿主进程时同样拒绝。这些情况都不回退到其他身份。未传参数时保留环境变量及 PID 唯一匹配,
|
|
85
|
+
兼容原来的单会话模式;无法识别时仍允许匿名查看会话列表,但 `list_reservations` 会报错,因为无从确定该查哪个仓库。
|
|
86
|
+
|
|
87
|
+
更新后需要重新连接 CC Bridge MCP(或重启使用它的客户端),才能加载新程序和带 `session_id` 的工具定义。
|
|
88
|
+
|
|
74
89
|
### 会话名
|
|
75
90
|
|
|
76
91
|
默认名字是 `<账号名>.<项目目录名>.<动物>`,例如 `claude.my-app.otter`、`claude-x.my-app.panda`。账号名取多账号页里的名称
|
|
@@ -113,11 +128,13 @@ CC_BRIDGE_NAME=api codex
|
|
|
113
128
|
| 通知对方 | 用 cc-bridge 告诉 api:登录接口改成了 POST /api/login,返回字段加了 token,你那边同步改一下前端调用 |
|
|
114
129
|
| 分派任务 | 让 web 帮忙写 src/api/login.ts 的单元测试,写完告诉我结果 |
|
|
115
130
|
| 要对方回复 | 问一下 api 数据库迁移做到哪一步了,让它用 cc-bridge 回复你 |
|
|
116
|
-
|
|
|
131
|
+
| 等对方回复 | 给 api 发消息让它跑一遍测试,跑完用 cc-bridge 把结果发给你 |
|
|
132
|
+
| 看对方何时空闲 | 给 api 发消息,并在它空闲时通知你 |
|
|
117
133
|
| 按终端指定 | 发给 ttys003 那个 Claude 会话:…… |
|
|
118
134
|
|
|
119
135
|
对方的回复会作为一条新消息出现在当前会话里。"在它空闲时通知你"会让对方这一轮做完后,
|
|
120
|
-
当前会话收到一条一次性的空闲通知(`notify_when_idle
|
|
136
|
+
当前会话收到一条一次性的空闲通知(`notify_when_idle`)。对方忙碌时,这一轮可能是收到消息前就在进行的回合,
|
|
137
|
+
所以通知只表示对方结束了一个回合,不代表你的任务已完成。要等结果,请让对方做完后回复你。
|
|
121
138
|
|
|
122
139
|
### 多个会话改同一个仓库
|
|
123
140
|
|
|
@@ -151,7 +168,7 @@ CC_BRIDGE_NAME=api codex
|
|
|
151
168
|
Bridge 优先验证当前进程提供的 `CODEX_THREAD_ID` / `CLAUDE_CODE_SESSION_ID`,包括注册记录、
|
|
152
169
|
在线状态和宿主是否一致。没有会话 ID 时,仅允许宿主 PID 唯一匹配一个在线会话。
|
|
153
170
|
多个会话共享 PID 且缺少可靠 ID,或显式 ID 已失效时,会明确拒绝发送、改名、收件和文件预留等操作,
|
|
154
|
-
不会按最近活跃时间猜测。CLI 排查时可用 `--from <会话名或完整会话 ID>`
|
|
171
|
+
不会按最近活跃时间猜测。CLI 排查时可用 `--from <会话名或完整会话 ID>` 显式指定身份;`send` 的 `--from` 要写在正文之前。
|
|
155
172
|
|
|
156
173
|
## 文件预留
|
|
157
174
|
|
|
@@ -175,7 +192,7 @@ Bridge 优先验证当前进程提供的 `CODEX_THREAD_ID` / `CLAUDE_CODE_SESSIO
|
|
|
175
192
|
| Codex | 通过 `codex queue` 立即唤醒 | 排在当前回合之后处理 | 不投递,回执为 undeliverable |
|
|
176
193
|
| Claude Code | 后台 watcher 通过 `asyncRewake` 唤醒 | 注入当前回合 | 不投递,回执为 undeliverable |
|
|
177
194
|
|
|
178
|
-
Claude Code 的 watcher
|
|
195
|
+
Claude Code 的 watcher 在会话启动和每轮结束时挂上,新挂上的会取代旧的并重新计时,最多等待约 55 分钟后自动退出。
|
|
179
196
|
如果 Claude 会话在这段空窗期里一直空闲,消息会留在信箱,等用户下次输入时一并带入;
|
|
180
197
|
那一轮进行中新到的消息,在该轮结束时投递。
|
|
181
198
|
|
|
@@ -188,6 +205,11 @@ Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多
|
|
|
188
205
|
信箱消息认领后保留在 `claimed`,完整输出并刷新输出流成功后才确认。进程异常退出时,下一次
|
|
189
206
|
hook、watcher 或 `check_inbox` 会恢复未确认消息。在输出已到达宿主、确认尚未落盘的瞬间崩溃,
|
|
190
207
|
恢复后可能重复投递同一个消息 ID;目前没有宿主确认协议,无法保证恰好一次送达。
|
|
208
|
+
`codex queue` 超时时无法确定消息是否已入队,消息会同时放进信箱,发送方会收到可能重复的提示,两份消息的 ID 相同。
|
|
209
|
+
会话崩溃或被杀时不会触发 `SessionEnd`:下一次查询在线列表时发现它已离线,或下一个会话启动时,
|
|
210
|
+
它未投递的消息会被清理,回执标记为 undeliverable,空闲订阅也一并移除。
|
|
211
|
+
共享 app-server 的 Codex 线程在后台运行:关闭终端标签后,线程不会立刻结束,要等 app-server 卸载它才触发 `SessionEnd`,
|
|
212
|
+
实测有几分钟以内的延迟。在此之前它仍显示在线,发给它的消息可能进入队列,并在恢复该线程时执行。
|
|
191
213
|
跨账号投递 Codex 使用接收方注册的 Home;旧记录无法确定 Home 时保留到信箱,等待该会话输入后刷新注册。
|
|
192
214
|
|
|
193
215
|
## 桌宠里的显示
|
|
@@ -223,7 +245,8 @@ hook、watcher 或 `check_inbox` 会恢复未确认消息。在输出已到达
|
|
|
223
245
|
这条消息不能提升权限:不能用来修改权限或配置,不能当作对待确认操作的批准;如果对方说某个操作
|
|
224
246
|
在它那边被拒绝、请你代为执行,Agent 应拒绝并告知用户。
|
|
225
247
|
- 消息正文保存在当前用户的临时目录(`getconf DARWIN_USER_TEMP_DIR` 下的 `cc-bridge-<uid>/`),
|
|
226
|
-
目录权限为 `0700`、文件权限为 `0600`,未投递的消息 24
|
|
248
|
+
目录权限为 `0700`、文件权限为 `0600`,未投递的消息 24 小时后过期(在下一个会话启动时清理)。
|
|
249
|
+
消息送达后正文随之删除。回执只保存发送方、接收方、时间和状态,不含正文,保留约 48 小时用于排查。
|
|
227
250
|
这是对 [Provider 协议](./PROVIDER_PROTOCOL.zh-CN.md)"不接收正文"原则的一个显式例外,
|
|
228
251
|
所以默认关闭,需要你主动开启。
|
|
229
252
|
- 单条消息最多 16KB。同一对会话 10 分钟内往来超过 20 条会被暂停,防止两个 Agent 互相自动回复形成循环。
|
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,61 @@ truth for the version.
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.5.0] - 2026-11-15
|
|
11
|
+
|
|
12
|
+
### Menu bar
|
|
13
|
+
|
|
14
|
+
- Add a menu bar icon, chosen under Settings → Show In: Desktop Pet (default), Pet + Menu Bar, or Menu Bar Only.
|
|
15
|
+
- Left-click opens a compact glass panel: the pet's current status, up to five online sessions (click to jump to the terminal), a 5-hour quota ring per account, today's tokens, and Show Pet / Main menu. Right-click opens the pet's context menu.
|
|
16
|
+
- The menu bar icon is an outlined terminal window whose color follows the status card (blue working, green completed, red failed); awaiting approval switches the `>_` prompt to orange `•••` and returns to the normal menu bar color when the card goes back to idle. Plan accounts are listed before API accounts in the panel.
|
|
17
|
+
- While a session awaits approval, left-clicking the icon jumps straight to its terminal; ⌥-click opens the panel.
|
|
18
|
+
- The icon shows the number of sessions awaiting approval and, optionally, the lowest 5-hour quota left (orange at 20% or below, red at 10%). The number follows the switch only.
|
|
19
|
+
- Menu Bar Only hides the pet and its status card, bubbles and hover panel. Chatter is skipped without using its budget; tracking and notifications continue.
|
|
20
|
+
- The phrases editor's Try a Line explains that the pet is hidden in Menu Bar Only.
|
|
21
|
+
|
|
22
|
+
### Status card
|
|
23
|
+
|
|
24
|
+
- Show the session instead of the agent in the title ("session · status"), so concurrent sessions can be told apart at a glance. With CC Bridge enabled the label is `directory.animal` (for example `cc-pets.crab`); otherwise it is the working directory name, falling back to the agent name when neither is known. Long labels are truncated in the middle and keep the trailing animal suffix.
|
|
25
|
+
- Hovering the status card shows the full session name and working directory.
|
|
26
|
+
- Accept optional working-directory metadata in provider events for session labels and tooltips, falling back to the event command's current directory.
|
|
27
|
+
|
|
28
|
+
### CC Bridge
|
|
29
|
+
|
|
30
|
+
- Show Chinese animal aliases alongside automatically generated session names in Chinese UI, CLI output, messages and notifications. Keep original names and refs as message addresses; custom names remain unchanged.
|
|
31
|
+
- Exclude transient Codex tasks without persisted transcripts from message-recipient registration while retaining their pre-edit file reservation checks.
|
|
32
|
+
- Accept a per-call `session_id` in MCP tools, supplied through session-start and user-prompt hook context, so Codex sessions sharing an app-server PID can identify themselves when MCP does not inherit a session ID. Explicit identities must pass live-registration and host checks; retain single-session auto-detection, reject invalid IDs and never cache caller identity.
|
|
33
|
+
- Keep `config.toml` byte-for-byte outside CC Bridge's own managed block, including blank lines inside multi-line strings and marker-like text.
|
|
34
|
+
- Recognize CLI hosts from structured argv so paths containing spaces work. Rejected `session_id` values now report why, and an unverifiable host is still rejected.
|
|
35
|
+
- Serialize reservation creation, renewal, acknowledgement, release and expiry so concurrent sessions can't miss conflicts or lose updates.
|
|
36
|
+
- Detect overlaps between directories and globs, such as `src/api` and `src/**/*.ts`, by checking whether a common path exists.
|
|
37
|
+
- Clean up after sessions that exit without `SessionEnd`: mark undelivered messages undeliverable, expire old messages and receipts, and remove idle subscriptions.
|
|
38
|
+
- Reject invalid `paths` in `release_files` without changing any reservation.
|
|
39
|
+
- Make send limits atomic so concurrent sessions can't exceed them.
|
|
40
|
+
- Resolve symlinks in repository roots and reserved paths, including new files and globs, so reservations match however a session reached the directory.
|
|
41
|
+
- Keep the newest deliveries in the pet's badge and notifications when receipts exceed the scan limit.
|
|
42
|
+
- Use the same online check in the pet as in the CLI.
|
|
43
|
+
- Report the right count in the "and N more" delivery notification.
|
|
44
|
+
- Recognize only real `mcp_servers` declarations when uninstalling, so matching text in project paths no longer causes false removal errors.
|
|
45
|
+
- Treat `--from` after the first two `send` arguments as message text, and reject unknown options and flags missing a value.
|
|
46
|
+
- Stop treating patch-like text in written content as edited files, and skip `git` when no reservations exist.
|
|
47
|
+
- Answer MCP requests with invalid UTF-8 with a parse error instead of no response.
|
|
48
|
+
- Return an error from `list_reservations` when the caller is unknown instead of checking the MCP process directory.
|
|
49
|
+
- Stop storing message bodies in receipts, so a body is deleted once its message is delivered.
|
|
50
|
+
- Delete undelivered messages on `disable` and mark their receipts undeliverable.
|
|
51
|
+
- When `codex queue` times out, keep the inbox fallback and warn the sender that the message may arrive twice.
|
|
52
|
+
- `release_files` with an empty `paths` array now releases nothing; omit `paths` to release everything.
|
|
53
|
+
- Skip inbox locking while the watcher's inbox is empty, and clarify what `notify_when_idle` guarantees.
|
|
54
|
+
- Let each new watcher replace the previous one and restart the wait, so active sessions stay wakeable for about 55 minutes after every turn.
|
|
55
|
+
- Enqueue under the inbox lock and recheck that Bridge is on and the recipient is online, so a slow send can't leave a body behind after `disable` or a session exit.
|
|
56
|
+
- Follow symlinks before resolving `..` in reserved paths, and recognize quoted `mcp_servers` keys at every level when uninstalling.
|
|
57
|
+
|
|
58
|
+
### Session lifecycle
|
|
59
|
+
|
|
60
|
+
- Match shared-host Codex terminal launches against unique TUI readiness records within one second before or after session creation, covering initial frames logged just after creation without guessing between concurrent clients.
|
|
61
|
+
- Track persistent Codex desktop chats against the current app instance, include them in online counts, and keep the pet running while Codex desktop is open after the last managed CLI exits. Ignore transient background tasks and restore recent desktop records without replaying animations or notifications.
|
|
62
|
+
- Record Codex session-end hooks, remove ended sessions and pending approvals, and switch the displayed session or return to idle without a completion animation. Ignore trailing events after a turn completes.
|
|
63
|
+
- Preserve profile-ID separators and normalize legacy IDs so account matching stays consistent. Track managed CLI exits per session instead of excluding other sessions from the same provider.
|
|
64
|
+
|
|
10
65
|
## [2.4.0] - 2026-11-03
|
|
11
66
|
|
|
12
67
|
### Diagnostics
|
package/CHANGELOG.zh-CN.md
CHANGED
|
@@ -6,6 +6,61 @@
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [2.5.0] - 2026-11-15
|
|
10
|
+
|
|
11
|
+
### 菜单栏
|
|
12
|
+
|
|
13
|
+
- 新增菜单栏图标,在「设置 → 显示位置」选择:仅桌宠(默认)、桌宠 + 菜单栏、仅菜单栏。
|
|
14
|
+
- 左键打开精简的玻璃面板:宠物当前状态、最多 5 个在线会话(点击跳到终端)、每个账号一个 5 小时额度环、今日用量,以及显示桌宠、主菜单。右键打开与桌宠相同的右键菜单。
|
|
15
|
+
- 菜单栏图标是带 `>_` 的描边终端窗口,颜色与状态卡同步(工作中蓝、完成绿、失败红),等待审批时 `>_` 换成橙色 `•••`,状态卡回落待机时恢复原色。面板中订阅账号排在 API 账号之前。
|
|
16
|
+
- 有会话等待审批时,左键点图标直接跳到该会话的终端;按住 ⌥ 点击打开面板。
|
|
17
|
+
- 图标旁显示等待审批的会话数,可选显示最低的 5 小时剩余额度(20% 及以下橙色,10% 及以下红色),是否显示只看开关。
|
|
18
|
+
- 仅菜单栏时隐藏桌宠及其状态卡、气泡和悬停面板。碎碎念直接跳过、不占预算;状态跟踪和系统通知照常。
|
|
19
|
+
- 仅菜单栏时,台词编辑器的「试说一句」会提示桌宠已隐藏。
|
|
20
|
+
|
|
21
|
+
### 状态卡
|
|
22
|
+
|
|
23
|
+
- 标题由「智能体 · 状态」改为「会话 · 状态」,多个会话同时运行时能直接看出是哪一个。开启 CC Bridge 时显示「目录名.动物」(如 `cc-pets.crab`),否则显示工作目录名;取不到时仍显示智能体名称。过长的标签截掉中间、保留末尾的动物后缀。
|
|
24
|
+
- 悬停状态卡显示完整会话名和工作目录。
|
|
25
|
+
- Provider 事件支持可选的工作目录信息,用于会话标签与悬停提示;未提供或无效时回退到事件命令的当前目录。
|
|
26
|
+
|
|
27
|
+
### CC Bridge
|
|
28
|
+
|
|
29
|
+
- 中文界面、CLI 输出、消息与通知为自动生成的会话名附加中文动物别名;消息寻址仍使用原始名称和 ref,自定义名称保持不变。
|
|
30
|
+
- 没有持久化转录的 Codex 临时任务不再注册为消息收件人,但仍执行编辑前的文件预留检查。
|
|
31
|
+
- MCP 工具支持逐次传入 `session_id`,由会话启动及用户输入 hook 提供当前身份,修复多个 Codex 会话共用 app-server PID 且 MCP 未继承会话 ID 时无法识别调用者的问题。显式身份须通过在线注册及宿主校验;保留单会话自动识别,拒绝无效 ID 且不缓存调用者身份。
|
|
32
|
+
- `config.toml` 只改 CC Bridge 自身的管理块,其余内容逐字保留,包括多行字符串里的空行和形似标记的文本。
|
|
33
|
+
- 通过结构化 argv 识别 CLI 宿主,修复路径含空格时识别失败的问题。`session_id` 被拒绝时会说明原因,无法验证宿主时仍然拒绝。
|
|
34
|
+
- 文件预留的创建、续期、确认、释放和过期删除改为串行执行,避免并发会话漏检冲突或丢失更新。
|
|
35
|
+
- 通过判断是否存在共同路径来检测目录与 glob 的重叠,例如 `src/api` 与 `src/**/*.ts`。
|
|
36
|
+
- 补全未触发 `SessionEnd` 就退出的会话的清理:未投递消息标记为 undeliverable,过期消息和回执收尾,并移除空闲订阅。
|
|
37
|
+
- `release_files` 收到非法 `paths` 时报错,且不改动任何预留。
|
|
38
|
+
- 发送限额改为原子操作,并发会话不会越过上限。
|
|
39
|
+
- 解析仓库根和预留路径中的软链,包括新文件和 glob,无论会话从哪条路径进入目录,预留都能对上。
|
|
40
|
+
- 回执数超过扫描上限时,桌宠的角标和通知仍保留最新送达的消息。
|
|
41
|
+
- 桌宠与 CLI 使用同一套在线判断规则。
|
|
42
|
+
- 修正送达通知里“另外 N 条”的数量。
|
|
43
|
+
- 卸载时只识别真正的 `mcp_servers` 声明,项目路径中的相同文字不再导致误报移除失败。
|
|
44
|
+
- `send` 前两个参数之后的 `--from` 视为消息正文;未知选项和缺值的参数会报错。
|
|
45
|
+
- 写入内容里形似补丁的文本不再算作被编辑的文件;没有预留时跳过 `git` 调用。
|
|
46
|
+
- 含非法 UTF-8 的 MCP 请求返回解析错误,不再没有响应。
|
|
47
|
+
- 调用者身份未知时,`list_reservations` 返回错误,不再查询 MCP 进程所在目录。
|
|
48
|
+
- 回执不再保存消息正文,消息送达后正文即被删除。
|
|
49
|
+
- `disable` 时删除未投递的消息,回执标记为 undeliverable。
|
|
50
|
+
- `codex queue` 超时时仍回退到信箱,并提示发送方消息可能到达两次。
|
|
51
|
+
- `release_files` 传空数组时不再释放任何预留;不传 `paths` 才会全部释放。
|
|
52
|
+
- watcher 在信箱为空时不再加锁,并明确 `notify_when_idle` 的保证范围。
|
|
53
|
+
- 新 watcher 取代旧的并重新计时,活跃会话在每轮结束后约 55 分钟内都能被唤醒。
|
|
54
|
+
- 入信箱时持有信箱锁,并复查 Bridge 开关和收件方在线状态,发送缓慢时不会在 `disable` 或会话退出后留下正文。
|
|
55
|
+
- 预留路径先解析软链再处理 `..`;卸载时识别每一级都带引号的 `mcp_servers` 键。
|
|
56
|
+
|
|
57
|
+
### 会话生命周期
|
|
58
|
+
|
|
59
|
+
- 共享宿主下的 Codex 终端匹配改为查询会话创建前后一秒内唯一的 TUI 就绪记录,兼容首帧稍晚于会话创建才记录的情况,多个客户端并发时仍不猜测归属。
|
|
60
|
+
- 按当前应用实例跟踪 Codex 桌面端的持久化聊天,将其计入在线数量;最后一个托管 CLI 退出后,Codex 桌面端仍运行时保留桌宠。过滤后台临时任务,恢复近期桌面会话记录时不重播动画或通知。
|
|
61
|
+
- 记录 Codex 会话结束 Hook,清理已结束会话和待审批记录,并切换展示会话或直接恢复待机,不误播完成动画;回合完成后的尾随事件不再覆盖终态。
|
|
62
|
+
- 保留账号 ID 的分隔符并兼容旧格式,修复账号匹配;按具体会话跟踪托管 CLI 退出,避免误排除同一 Provider 的其他会话。
|
|
63
|
+
|
|
9
64
|
## [2.4.0] - 2026-11-03
|
|
10
65
|
|
|
11
66
|
### 诊断
|
|
@@ -46,7 +101,7 @@
|
|
|
46
101
|
|
|
47
102
|
### 启动保护
|
|
48
103
|
|
|
49
|
-
-
|
|
104
|
+
- 新增可选的 Shadowrocket 启动检查,位于「主菜单 → 设置 → 启动保护」,默认关闭。包装器在登记会话、发送 starting 事件之前检查 VPN 连接状态,并分别请求服务的 `/cdn-cgi/trace`。中国大陆(CN)、香港(HK)、未知出口及请求失败均阻止启动;成功显示出口 IP 和地区。
|
|
50
105
|
- Claude 默认检查 `api.anthropic.com`;Codex 按 `auth.json` 的登录模式检查 `chatgpt.com` 或 `api.openai.com`,模式未知时检查两者。支持用户级常见端点配置;自定义地址必须返回有效 trace,不回退到无关域名。移除独立 DNS / 首页 HEAD 探测,不携带账号凭据、校验 TLS 证书、忽略 `~/.curlrc`、不跟随重定向。复杂配置、项目网络覆盖及云服务商的支持边界见 README;绕过包装器的启动不受保护。
|
|
51
106
|
- 出口检测调整为连接时限 8 秒、单次请求时限 15 秒、进程保护时限 16 秒;临时传输故障和 HTTP 502 / 503 / 504 间隔 1 秒重试一次。失败时显示超时阶段、尝试次数及连接累计耗时。包装器测试每轮使用独立偏好域,避免读取真实 VPN 设置并发起网络探测,保留编译缓存和阶段计时。
|
|
52
107
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -43,7 +43,7 @@ Install preview builds explicitly; the automatic updater accepts stable versions
|
|
|
43
43
|
`main` is reserved for stable releases, including the stable GitHub Release and tag.
|
|
44
44
|
Complete implementation, documentation, screenshots, and validation on `publish`
|
|
45
45
|
before submitting to `main`; repeat integration checks there before a stable release.
|
|
46
|
-
The latest stable GitHub release is **v2.
|
|
46
|
+
The latest stable GitHub release is **v2.4.0**, covering exact terminal jumps, optional launch protection, CC Bridge reliability, token accounting, and clearer local version diagnostics.
|
|
47
47
|
See [release status](docs/release-status.md) for validation and handoff details.
|
|
48
48
|
|
|
49
49
|
## Localization
|
package/CONTRIBUTING.zh-CN.md
CHANGED
|
@@ -36,7 +36,7 @@ prerelease,并使用如 `2.2.1-rc.1` 的预发布版本号。`main` 仅负责
|
|
|
36
36
|
GitHub Release 和 tag。提交到 `main` 前,代码、文档、截图与验证必须全部完成;
|
|
37
37
|
在 `main` 完成集成验证后才能发布正式版本。
|
|
38
38
|
测试版本需显式安装,自动更新器只接受正式版本号。
|
|
39
|
-
当前 GitHub 正式版本为 **v2.
|
|
39
|
+
当前 GitHub 正式版本为 **v2.4.0**,包含终端精准跳转、可选启动保护、CC Bridge 可靠性改进、Token 统计修正及更清晰的本地版本诊断。
|
|
40
40
|
验证和交接状态见[发布状态](docs/release-status.md)。
|
|
41
41
|
|
|
42
42
|
## 多语言
|
package/PROVIDER_PROTOCOL.md
CHANGED
|
@@ -4,7 +4,7 @@ English | [简体中文](./PROVIDER_PROTOCOL.zh-CN.md)
|
|
|
4
4
|
|
|
5
5
|
Third-party CLI agents can write normalized status events to CC Pets through
|
|
6
6
|
standard input and reuse its status card, animations, and optional system
|
|
7
|
-
notifications. The protocol accepts status
|
|
7
|
+
notifications. The protocol accepts status, tool categories, and working-directory metadata. It does not
|
|
8
8
|
accept prompts, command text, file contents, or model output.
|
|
9
9
|
|
|
10
10
|
## Sending an event
|
|
@@ -22,6 +22,10 @@ printf '%s' '{
|
|
|
22
22
|
letters, digits, spaces, `.`, `_`, and `-`. `tool` is optional, has a maximum length
|
|
23
23
|
of 64 characters, and is used only to select redacted status text and animation.
|
|
24
24
|
|
|
25
|
+
`cwd` is optional and supplies the working directory for the session label and tooltip.
|
|
26
|
+
It must be an absolute path of at most 1,024 UTF-16 code units without control characters.
|
|
27
|
+
If omitted or invalid, CC Pets uses the event command's current working directory.
|
|
28
|
+
|
|
25
29
|
`state` must be one of these values:
|
|
26
30
|
|
|
27
31
|
| State | Meaning |
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[English](./PROVIDER_PROTOCOL.md) | 简体中文
|
|
4
4
|
|
|
5
5
|
第三方 CLI Agent 可以通过标准输入向 CC Pets 写入统一状态事件,从而复用状态气泡、
|
|
6
|
-
|
|
6
|
+
桌宠动画和可选的系统通知。协议接收状态类别、工具类别和工作目录信息,不接收提示词、命令正文、
|
|
7
7
|
文件内容或模型输出。
|
|
8
8
|
|
|
9
9
|
## 发送事件
|
|
@@ -20,6 +20,9 @@ printf '%s' '{
|
|
|
20
20
|
`provider` 必填,最长 32 个字符,仅保留字母、数字、空格、`.`、`_` 和 `-`。
|
|
21
21
|
`tool` 可选,最长 64 个字符,仅用于选择脱敏后的状态文案和动画。
|
|
22
22
|
|
|
23
|
+
`cwd` 可选,用于会话标签和悬停提示。必须是绝对路径,最长 1,024 个 UTF-16 码元,
|
|
24
|
+
且不能含控制字符。未提供或无效时,使用事件命令的当前工作目录。
|
|
25
|
+
|
|
23
26
|
`state` 必须是下列值之一:
|
|
24
27
|
|
|
25
28
|
| state | 含义 |
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="docs/images/cover.png" alt="CC Pets v2.
|
|
2
|
+
<img src="docs/images/cover.png" alt="CC Pets v2.5.0: Menu bar mode, clearer sessions and CC Bridge reliability">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
# CC Pets
|
|
@@ -13,16 +13,16 @@ Codex App Server interface and Claude Code's official status line input.
|
|
|
13
13
|
|
|
14
14
|
> The app and CLI are available in English and Simplified Chinese (see [Language](#language)).
|
|
15
15
|
|
|
16
|
-
## What's new in v2.
|
|
16
|
+
## What's new in v2.5.0
|
|
17
17
|
|
|
18
|
-
- **
|
|
19
|
-
|
|
20
|
-
- **
|
|
21
|
-
|
|
22
|
-
- **
|
|
23
|
-
|
|
18
|
+
- **Menu bar mode** — keep the pet, add a menu bar panel, or use the menu bar alone;
|
|
19
|
+
check sessions and quota, and jump straight to a terminal awaiting approval.
|
|
20
|
+
- **Clearer sessions** — identify status cards by session, track persistent Codex
|
|
21
|
+
desktop chats, and clear ended sessions without replaying completion animations.
|
|
22
|
+
- **CC Bridge reliability** — identify shared-host callers per tool call, improve
|
|
23
|
+
concurrent file reservations and message cleanup, and preserve unrelated config.
|
|
24
24
|
|
|
25
|
-
See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
25
|
+
See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.5.0.md) for the full list.
|
|
26
26
|
|
|
27
27
|
## Screenshots
|
|
28
28
|
|
|
@@ -34,7 +34,7 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
|
34
34
|
|
|
35
35
|
- Supports English and Simplified Chinese in the app and CLI, with live UI language switching.
|
|
36
36
|
- Offers Classic and native Liquid Glass panel themes on macOS 26 and later.
|
|
37
|
-
- Starts with Codex CLI or Claude Code CLI and closes after the last managed CLI exits.
|
|
37
|
+
- Starts with Codex CLI or Claude Code CLI and closes after the last managed CLI exits, unless Codex desktop is still running.
|
|
38
38
|
- Shares one pet across multiple simultaneous Codex and Claude sessions.
|
|
39
39
|
- Shows five-hour and weekly remaining quota, reset times, local token totals, and seven-day trends.
|
|
40
40
|
- Converts reset times to the Mac's current system time zone.
|
|
@@ -53,6 +53,7 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
|
53
53
|
selection persists across pet changes and restarts, with pet-specific lines selected initially.
|
|
54
54
|
- Includes one original pet and can download compatible assets from PetDex.
|
|
55
55
|
- Opens the Main menu, a regular app window with an overview, your sessions and CC Bridge messages, token usage by model, every setting and built-in diagnostics (see [Main menu](#main-menu)).
|
|
56
|
+
- Can also live in the menu bar: sessions, per-account quota and today's tokens one click away, or hide the desktop pet entirely (see [Menu bar](#menu-bar)).
|
|
56
57
|
- Uses native AppKit with no Electron runtime.
|
|
57
58
|
|
|
58
59
|
## Requirements
|
|
@@ -198,6 +199,12 @@ configuration, not just its running process. Original CLI binaries and desktop c
|
|
|
198
199
|
and Codex sessions exchange messages and reserve files. Session IDs are validated;
|
|
199
200
|
PID fallback is accepted only for a unique live session. Ambiguous shared-host identities
|
|
200
201
|
are rejected rather than guessed. Codex delivery uses the recipient's Home.
|
|
202
|
+
For Codex sessions sharing an app-server PID, agents pass the current `session_id` from
|
|
203
|
+
Bridge hook context on each MCP call. Reconnect MCP after updating to load the new tool definitions.
|
|
204
|
+
|
|
205
|
+
In Chinese, generated session names include an animal alias for readability; use the
|
|
206
|
+
original name or ref when addressing messages. Transient Codex tasks without persisted
|
|
207
|
+
transcripts are not registered as recipients, but still receive file reservation checks.
|
|
201
208
|
|
|
202
209
|
Unconfirmed inbox messages are recoverable after a crash. A crash between output and
|
|
203
210
|
confirmation may repeat the same message ID; delivery does not mean the recipient has
|
|
@@ -273,10 +280,23 @@ supported. See [extension details](plugins/vscode/README.md).
|
|
|
273
280
|
|
|
274
281
|
### Codex and Claude hooks
|
|
275
282
|
|
|
283
|
+
Status card titles show the session and its state. Generated CC Bridge names use the
|
|
284
|
+
short `directory.animal` form; custom names are preserved. Without a Bridge name, the
|
|
285
|
+
card uses the working directory name, falling back to the agent name. Hover to see
|
|
286
|
+
the full session name and working directory. Long titles retain the animal suffix.
|
|
287
|
+
|
|
276
288
|
Codex Hooks and Claude Code Hooks drive the pet's agent-state animations. After a
|
|
277
289
|
first installation or a Codex Hook update, start Codex and run `/hooks` to review
|
|
278
290
|
and trust the CC Pets Hook. Codex skips untrusted user hooks.
|
|
279
291
|
|
|
292
|
+
Persistent Codex desktop chats also appear in the session list and online counts while
|
|
293
|
+
their app instance is running. Transient background tasks are excluded. Restarting CC Pets
|
|
294
|
+
can restore recent desktop records without replaying animations or notifications; unfinished
|
|
295
|
+
states return as idle. A session-end event removes the chat and switches to another live
|
|
296
|
+
session or returns the pet to idle, without a completion animation. Without an end event,
|
|
297
|
+
a desktop chat may remain listed until its app exits. Desktop start events do not play
|
|
298
|
+
the CLI startup animation.
|
|
299
|
+
|
|
280
300
|
The Claude Code integration merges into `~/.claude/settings.json` while preserving
|
|
281
301
|
existing `env`, `model`, `statusLine`, and hook settings. Its quota collector is
|
|
282
302
|
injected into the existing status line script without changing the configured
|
|
@@ -339,7 +359,7 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
|
|
|
339
359
|
- **Multi-Account** — add Claude / Codex Homes, view paths and integration status, and manage repairs, names, relocation and removal of custom Home integrations.
|
|
340
360
|
- **Pet / Alerts / Settings** — every pet setting, split into three short pages (Pet:
|
|
341
361
|
picker, deletion of unselected custom pets with confirmation, size, chatter, click reactions and Codex import; Alerts: notifications, the status
|
|
342
|
-
card and system status; Settings: language, panel appearance and the pet sprites folder), plus finer controls such as the click-reaction thresholds and a
|
|
362
|
+
card and system status; Settings: language, display location, panel appearance and the pet sprites folder), plus finer controls such as the click-reaction thresholds and a
|
|
343
363
|
continuous glass dimming slider (the menu keeps its four presets). Changes apply to the
|
|
344
364
|
desktop pet immediately, and changes made in the menu show up here. Options that rewrite
|
|
345
365
|
Claude Code / Codex configuration (enabling CC Bridge, auto-approve) stay in the
|
|
@@ -359,9 +379,42 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
|
|
|
359
379
|
`manifest.json` records original paths, permissions and backup files. Other issues retain
|
|
360
380
|
their manual commands. Plain `cc-pets doctor` remains read-only.
|
|
361
381
|
|
|
362
|
-
The window is created when you open it and released when you close it
|
|
363
|
-
|
|
364
|
-
clicking the Dock icon brings a minimized window back.
|
|
382
|
+
The Main menu window is created when you open it and released when you close it; its pages
|
|
383
|
+
do not run background tasks while closed. The Dock icon and application menus appear only
|
|
384
|
+
while the window is open; clicking the Dock icon brings a minimized window back. The optional
|
|
385
|
+
menu bar status icon follows Settings → Show In independently of this window.
|
|
386
|
+
|
|
387
|
+
### Menu bar
|
|
388
|
+
|
|
389
|
+
**Main menu → Settings → Show In** chooses where CC Pets appears: **Desktop Pet** (default),
|
|
390
|
+
**Pet + Menu Bar**, or **Menu Bar Only**. With a menu bar icon:
|
|
391
|
+
|
|
392
|
+
- **Left-click** opens a compact glass panel in the same style as the hover panel: the pet and
|
|
393
|
+
what it is doing, up to five online sessions (awaiting approval first; click one to jump to
|
|
394
|
+
its terminal), one row per account with a 5-hour quota ring, weekly quota left and the next
|
|
395
|
+
reset (API accounts show this month's tokens and calls; plan accounts are listed first), today's total tokens, **Show Pet**
|
|
396
|
+
and **Main menu**. When an update is available, **Update to x.y.z…** appears here too. Trends,
|
|
397
|
+
token breakdowns and system status stay in the hover panel and the Main menu. Click outside
|
|
398
|
+
the panel or press Esc to close it.
|
|
399
|
+
- **While a session awaits approval**, left-click jumps straight to its terminal instead (the
|
|
400
|
+
first one in the session list, so the next click goes to the next one). ⌥-click still opens
|
|
401
|
+
the panel, and the panel opens as usual when that session's terminal can't be resolved.
|
|
402
|
+
- **Right-click** (or Control-click) opens the same menu as right-clicking the pet, including
|
|
403
|
+
the CC Bridge switches and **Quit**.
|
|
404
|
+
- The icon is an outlined terminal window with a `>_` prompt that takes the status card's color:
|
|
405
|
+
normal menu bar color while idle, blue while an agent works, green after a task completes and
|
|
406
|
+
red after a failure. Awaiting approval, the only state that needs you, shows orange `•••`. It returns to the normal
|
|
407
|
+
menu bar color when the status card goes back to idle (about a minute without new events),
|
|
408
|
+
so Hook activity stays visible even with the pet hidden.
|
|
409
|
+
- The icon shows a red count of sessions awaiting approval. **Quota in Menu Bar** adds the
|
|
410
|
+
lowest 5-hour quota left among plan accounts, in orange at 20% or below and red at 10%. With
|
|
411
|
+
the switch off no number is shown, even when quota is low.
|
|
412
|
+
|
|
413
|
+
**Menu Bar Only** hides the pet, its status card, speech bubbles, update bubble and hover
|
|
414
|
+
panel. Chatter is skipped without using up its hourly budget, so low-quota warnings are only
|
|
415
|
+
visible as the menu bar color. Agent tracking, quota collection and system notifications keep
|
|
416
|
+
running. The icon goes away with the pet when the last managed CLI exits, unless
|
|
417
|
+
Codex desktop is still running. Standalone launches stay open until you quit.
|
|
365
418
|
|
|
366
419
|
## Pet interaction
|
|
367
420
|
|
|
@@ -542,9 +595,9 @@ external assets.
|
|
|
542
595
|
- 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.
|
|
543
596
|
- To tell API accounts from subscription accounts, CC Pets reads the authentication settings in each registered Home (Claude `settings.json`; Codex `auth.json` and `config.toml`) and may run that Home's `claude auth status` / `codex login status` locally. Only the resulting mode is kept, in memory; keys, emails and command output are not stored.
|
|
544
597
|
- Diagnostics repairs back up the affected configuration files and scripts to `~/Library/Application Support/CC Pets/diagnostic-backups/` (owner-only) before changing them; the backups stay on this Mac.
|
|
545
|
-
- Hooks write
|
|
598
|
+
- Hooks write redacted state events and quota cache files to the current user's temporary directory. Events may include working-directory, Home and transcript paths for session labels and lifecycle tracking, but not transcript contents.
|
|
546
599
|
- Local quota history is disabled by default and retains seven days when enabled.
|
|
547
|
-
- Status cards
|
|
600
|
+
- Status cards show session labels, state and redacted tool categories; tooltips may show the full session name and working directory. Agent notifications show provider and redacted status, without conversation content.
|
|
548
601
|
- CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
|
|
549
602
|
- 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 committed release notes from the tag through raw.githubusercontent.com, then jsDelivr, with the GitHub Release API as a fallback. These requests carry no account or usage data.
|
|
550
603
|
- Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
|