cc-pets 2.3.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.
Files changed (101) hide show
  1. package/CC_BRIDGE.md +63 -7
  2. package/CC_BRIDGE.zh-CN.md +43 -5
  3. package/CHANGELOG.md +106 -0
  4. package/CHANGELOG.zh-CN.md +106 -0
  5. package/CONTRIBUTING.md +23 -1
  6. package/CONTRIBUTING.zh-CN.md +18 -1
  7. package/PROVIDER_PROTOCOL.md +5 -1
  8. package/PROVIDER_PROTOCOL.zh-CN.md +4 -1
  9. package/README.md +177 -33
  10. package/README.zh-CN.md +137 -32
  11. package/Resources/AgentIcons/claude.png +0 -0
  12. package/Resources/AgentIcons/codex.icns +0 -0
  13. package/Resources/IDEPlugins/cc-pets-terminal.vsix +0 -0
  14. package/Resources/IDEPlugins/cc-pets-terminal.zip +0 -0
  15. package/Resources/zh-Hans.lproj/Localizable.strings +187 -35
  16. package/Sources/CCPets/App/CCPetsAppDelegate+AgentEvents.m +47 -4
  17. package/Sources/CCPets/App/CCPetsAppDelegate+AgentStatus.m +121 -20
  18. package/Sources/CCPets/App/CCPetsAppDelegate+Bridge.m +8 -6
  19. package/Sources/CCPets/App/CCPetsAppDelegate+MenuBar.m +86 -0
  20. package/Sources/CCPets/App/CCPetsAppDelegate+Private.h +14 -1
  21. package/Sources/CCPets/App/CCPetsAppDelegate+Quota.m +6 -1
  22. package/Sources/CCPets/App/CCPetsAppDelegate+Settings.m +3 -6
  23. package/Sources/CCPets/App/CCPetsAppDelegate+Speech.m +118 -50
  24. package/Sources/CCPets/App/CCPetsAppDelegate+Update.m +4 -1
  25. package/Sources/CCPets/App/CCPetsAppDelegate+Workbench.m +4 -0
  26. package/Sources/CCPets/App/CCPetsAppDelegate.h +12 -2
  27. package/Sources/CCPets/App/CCPetsAppDelegate.m +4 -2
  28. package/Sources/CCPets/App/main.m +6 -0
  29. package/Sources/CCPets/Bridge/CCPetsBridge.m +45 -18
  30. package/Sources/CCPets/Bridge/CCPetsBridgeCLI.m +175 -68
  31. package/Sources/CCPets/Bridge/CCPetsBridgeCore.h +14 -6
  32. package/Sources/CCPets/Bridge/CCPetsBridgeCore.m +356 -110
  33. package/Sources/CCPets/Bridge/CCPetsBridgeSetup.h +0 -2
  34. package/Sources/CCPets/Bridge/CCPetsBridgeSetup.m +247 -126
  35. package/Sources/CCPets/Bridge/CCPetsBridgeStore.h +37 -9
  36. package/Sources/CCPets/Bridge/CCPetsBridgeStore.m +385 -80
  37. package/Sources/CCPets/Integrations/CCPetsEvents.h +5 -0
  38. package/Sources/CCPets/Integrations/CCPetsEvents.m +68 -12
  39. package/Sources/CCPets/Integrations/CCPetsIDEIntegration.h +21 -0
  40. package/Sources/CCPets/Integrations/CCPetsIDEIntegration.m +503 -0
  41. package/Sources/CCPets/Integrations/CCPetsIntegrations.m +1 -1
  42. package/Sources/CCPets/Integrations/CCPetsLaunchPreflight.h +5 -0
  43. package/Sources/CCPets/Integrations/CCPetsLaunchPreflight.m +367 -0
  44. package/Sources/CCPets/Integrations/CCPetsTerminalFocus.h +8 -1
  45. package/Sources/CCPets/Integrations/CCPetsTerminalFocus.m +156 -25
  46. package/Sources/CCPets/Integrations/CCPetsTerminalIntegration.h +17 -0
  47. package/Sources/CCPets/Integrations/CCPetsTerminalIntegration.m +64 -0
  48. package/Sources/CCPets/Integrations/CCPetsVSCodeIntegration.h +23 -0
  49. package/Sources/CCPets/Integrations/CCPetsVSCodeIntegration.m +475 -0
  50. package/Sources/CCPets/Pet/CCPetsPhrasesEditor.m +7 -0
  51. package/Sources/CCPets/Pet/PetView+Menu.m +11 -3
  52. package/Sources/CCPets/Pet/PetView.h +7 -0
  53. package/Sources/CCPets/Pet/PetView.m +12 -1
  54. package/Sources/CCPets/Support/CCPetsDoctor.m +26 -12
  55. package/Sources/CCPets/Support/CCPetsPreferences.h +12 -0
  56. package/Sources/CCPets/Support/CCPetsPreferences.m +52 -2
  57. package/Sources/CCPets/UI/CCPetsFormBuilder.h +2 -0
  58. package/Sources/CCPets/UI/CCPetsFormBuilder.m +18 -7
  59. package/Sources/CCPets/UI/CCPetsGlassView.h +26 -4
  60. package/Sources/CCPets/UI/CCPetsGlassView.m +40 -9
  61. package/Sources/CCPets/UI/CCPetsMenuBarIcon.h +16 -0
  62. package/Sources/CCPets/UI/CCPetsMenuBarIcon.m +70 -0
  63. package/Sources/CCPets/UI/CCPetsMenuBarPanel.h +18 -0
  64. package/Sources/CCPets/UI/CCPetsMenuBarPanel.m +528 -0
  65. package/Sources/CCPets/UI/CCPetsMenuBarSummary.h +51 -0
  66. package/Sources/CCPets/UI/CCPetsMenuBarSummary.m +95 -0
  67. package/Sources/CCPets/UI/CCPetsSettingsPage.h +6 -1
  68. package/Sources/CCPets/UI/CCPetsSettingsPage.m +577 -66
  69. package/Sources/CCPets/UI/CCPetsStatusItem.h +28 -0
  70. package/Sources/CCPets/UI/CCPetsStatusItem.m +147 -0
  71. package/Sources/CCPets/UI/CCPetsUIStyle.h +5 -2
  72. package/Sources/CCPets/UI/CCPetsUIStyle.m +57 -8
  73. package/Sources/CCPets/UI/CCPetsUsageChartView.m +4 -0
  74. package/Sources/CCPets/UI/CCPetsUsagePage.m +23 -28
  75. package/Sources/CCPets/UI/CCPetsUsageStore.m +2 -2
  76. package/Sources/CCPets/UI/CCPetsWorkbenchPages.m +5 -3
  77. package/Sources/CCPets/Usage/CCPetsUsage+CodexBackground.m +193 -0
  78. package/Sources/CCPets/Usage/CCPetsUsage+Internal.h +1 -0
  79. package/Sources/CCPets/Usage/CCPetsUsage+Models.m +49 -11
  80. package/Sources/CCPets/Usage/CCPetsUsage.h +3 -2
  81. package/Sources/CCPets/Usage/CCPetsUsageMonitor.m +15 -17
  82. package/Sources/CCPets/Usage/QuotaDashboardView+Rendering.m +11 -29
  83. package/Sources/CCPets/Usage/QuotaDashboardView.m +128 -2
  84. package/THIRD_PARTY_NOTICES.md +7 -3
  85. package/THIRD_PARTY_NOTICES.zh-CN.md +5 -1
  86. package/bin/claude-with-pet +2 -0
  87. package/bin/codex-with-pet +2 -0
  88. package/package.json +5 -1
  89. package/plugins/jetbrains/README.md +62 -0
  90. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalBridge.java +379 -0
  91. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalIdentity.java +24 -0
  92. package/plugins/jetbrains/src/main/java/com/ccpets/terminal/TerminalStartup.java +12 -0
  93. package/plugins/jetbrains/src/main/resources/META-INF/plugin.xml +23 -0
  94. package/plugins/jetbrains/src/main/resources/META-INF/pluginIcon.svg +380 -0
  95. package/plugins/vscode/README.md +63 -0
  96. package/plugins/vscode/extension.js +210 -0
  97. package/plugins/vscode/package.json +18 -0
  98. package/scripts/build-idea-plugin.sh +101 -0
  99. package/scripts/build-vscode-extension.sh +112 -0
  100. package/scripts/build.sh +24 -2
  101. package/scripts/compile-cached.zsh +133 -0
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="docs/images/cover.png" alt="CC Pets v2.3.0: Main menu, multiple accounts and token usage by model">
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,32 +13,28 @@ 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.3.0
16
+ ## What's new in v2.5.0
17
17
 
18
- - **Main menu** — open Overview, Sessions, Usage, Pet, Multi-Account, Alerts,
19
- Settings and Diagnostics from the menu or `cc-pets open`. See live sessions, jump to their
20
- terminals and manage settings in one place.
21
- - **Multiple accounts and model usage** — manage Claude / Codex Homes from the
22
- Multi-Account page, with isolated quota, history and live state. Filter 7-, 30- and 90-day token charts
23
- by account and model, with per-account quota or API usage display.
24
- - **Native runtime and diagnostic repairs** — hooks, CC Bridge and CLI tools run
25
- without Node.js. Repair registered accounts' hooks and Claude status lines
26
- from Diagnostics, with configuration backups before changes.
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.
27
24
 
28
- See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.3.0.md) for the full list.
25
+ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.5.0.md) for the full list.
29
26
 
30
27
  ## Screenshots
31
28
 
32
29
  <p align="center">
33
- <img src="docs/images/liquid-glass-panel.en.png" width="45%" alt="English Agent Usage panel with quota, tokens, trends, and system status">
34
- <img src="docs/images/liquid-glass-menu.en.png" width="45%" alt="English right-click menu with English selected in the Language submenu">
30
+ <img src="docs/images/liquid-glass-panel.en.png" width="48%" alt="English Agent Usage panel with quota, tokens, trends, and system status"> <img src="docs/images/liquid-glass-menu.en.png" width="48%" alt="English right-click menu with English selected in the Language submenu">
35
31
  </p>
36
32
 
37
33
  ## Features
38
34
 
39
35
  - Supports English and Simplified Chinese in the app and CLI, with live UI language switching.
40
36
  - Offers Classic and native Liquid Glass panel themes on macOS 26 and later.
41
- - 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.
42
38
  - Shares one pet across multiple simultaneous Codex and Claude sessions.
43
39
  - Shows five-hour and weekly remaining quota, reset times, local token totals, and seven-day trends.
44
40
  - Converts reset times to the Mac's current system time zone.
@@ -57,6 +53,7 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
57
53
  selection persists across pet changes and restarts, with pet-specific lines selected initially.
58
54
  - Includes one original pet and can download compatible assets from PetDex.
59
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)).
60
57
  - Uses native AppKit with no Electron runtime.
61
58
 
62
59
  ## Requirements
@@ -109,10 +106,11 @@ the list after 60 idle seconds.
109
106
 
110
107
  Every hook status card is clickable. The circular status icon lists up to eight
111
108
  recent online Agent terminal sessions. Terminal.app and iTerm2 are selected
112
- precisely by TTY. Without an editor extension, VS Code, JetBrains IDEs, Warp,
113
- WezTerm, and Ghostty fall back to activating the owning application; selection of
114
- an internal tab is left to that application. macOS may request Automation
115
- permission on the first Terminal.app or iTerm2 jump.
109
+ precisely by TTY; Ghostty 1.4+ also selects the exact tab and split. VS Code and
110
+ JetBrains IDEs use their bundled extensions for exact terminal selection. Without
111
+ an extension, or for Warp, WezTerm and older Ghostty versions, the owning app is
112
+ brought forward. macOS may request Automation permission for Terminal.app, iTerm2
113
+ and Ghostty. Manage permissions and extensions in Settings → Terminal Jump.
116
114
 
117
115
  ### Install from source
118
116
 
@@ -157,6 +155,64 @@ Bridge is already enabled, its Hooks, permissions, and MCP registration are also
157
155
  configured immediately; otherwise they are added automatically when CC Bridge is
158
156
  enabled later.
159
157
 
158
+ ## Shadowrocket launch check
159
+
160
+ Enable **Main menu → Settings → Launch Protection → Shadowrocket** (off by default).
161
+ Each proxy app has its own preference; Shadowrocket is the first supported option.
162
+ CC Pets wrappers require a connected Shadowrocket VPN and a valid exit IP / region from
163
+ the service's HTTPS `/cdn-cgi/trace` endpoint before starting Claude / Codex. Failures
164
+ print a reason and return a nonzero exit code before registering a session or sending
165
+ a starting event. Disabling the option skips all network checks.
166
+
167
+ Claude defaults to `api.anthropic.com`. Codex uses the current Home's `auth.json` to select
168
+ `chatgpt.com` for ChatGPT login or `api.openai.com` for API-key login. If the mode is unknown
169
+ (for example, credentials stored only in Keychain), both exits must pass.
170
+ The response must contain valid `ip`, `loc` and matching `h` fields. `CN` and `HK` exits,
171
+ unknown regions, invalid responses, non-200 HTTP responses and connection / TLS / timeout
172
+ failures block launch. Successful probes print the domain, exit IP and region.
173
+ Each attempt has an 8-second connect timeout, a 15-second total request timeout and a
174
+ 16-second process watchdog. Temporary transport failures and HTTP 502 / 503 / 504 retry
175
+ once after 1 second; VPN status is checked again before retrying. Two timed-out requests
176
+ take about 31 seconds per domain, plus VPN checks and process overhead. Blocked regions,
177
+ invalid trace responses and certificate errors are not retried. Failure messages distinguish
178
+ connection, response and process timeouts and include attempt counts and cumulative DNS /
179
+ TCP / TLS / response timings. There is no separate DNS lookup or homepage HEAD request.
180
+ Probes send no account credentials,
181
+ verify TLS certificates, ignore `~/.curlrc` and do not follow redirects.
182
+
183
+ Claude reads network environment settings from the current `CLAUDE_CONFIG_DIR/settings.json`
184
+ and terminal proxy variables, including an overridden `ANTHROPIC_BASE_URL`. Codex supports
185
+ common single-line string routing settings in `CODEX_HOME/config.toml` (`model_provider`,
186
+ `profile`, `model_providers.<id>.base_url`, `chatgpt_base_url`), `--profile` / `-p`,
187
+ `OPENAI_BASE_URL` and terminal proxy variables. Custom endpoints use their own origin's
188
+ `/cdn-cgi/trace`, with no fallback to another domain. Gateways must serve valid trace data;
189
+ this only describes the exit to the gateway, not the gateway's upstream exit.
190
+ Complex routing TOML, unsupported cloud providers, command-line configuration overrides
191
+ and project network overrides are rejected with an explanation. Enterprise-managed network
192
+ configuration is outside the supported scope. The check does not validate account access,
193
+ service-supported countries or future routing changes. It recognizes the Shadowrocket VPN
194
+ configuration, not just its running process. Original CLI binaries and desktop clients bypass it.
195
+
196
+ ## CC Bridge
197
+
198
+ [CC Bridge](./CC_BRIDGE.md) is optional and off by default. It lets local Claude Code
199
+ and Codex sessions exchange messages and reserve files. Session IDs are validated;
200
+ PID fallback is accepted only for a unique live session. Ambiguous shared-host identities
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.
208
+
209
+ Unconfirmed inbox messages are recoverable after a crash. A crash between output and
210
+ confirmation may repeat the same message ID; delivery does not mean the recipient has
211
+ read or accepted it. Turning off auto-wake also stops existing watchers from taking new
212
+ messages. Disabling Bridge blocks CLI send, rename and inbox operations; incomplete
213
+ integration removal returns an error and can be retried. See the guide for configuration
214
+ and delivery details, and the [unreleased changelog](./CHANGELOG.md#unreleased) for fixes.
215
+
160
216
  ## Commands
161
217
 
162
218
  ```bash
@@ -198,10 +254,49 @@ Commit the bilingual `docs/release-notes-vX.Y.Z.md` before tagging; follow the
198
254
 
199
255
  ## Agent integration
200
256
 
257
+ ### JetBrains IDE terminal jump
258
+
259
+ Local Reworked terminals in IntelliJ-based IDEs 2026.2 / 2026.3 (IntelliJ IDEA,
260
+ PyCharm, WebStorm, GoLand, CLion, PhpStorm, RubyMine, Rider, etc.) support exact tab selection through
261
+ the **CC Pets Terminal** plugin. Open **Settings → General → Terminal Jump** in CC Pets:
262
+ each detected IDE has its own row, and **Install** writes the bundled plugin into that IDE's
263
+ plugin folder after you confirm. Restart the IDE if it was running, then open a project to
264
+ connect automatically; no port configuration is needed. When a newer plugin ships with
265
+ CC Pets, the row offers **Update**. IDEs with a customized plugin folder (`idea.plugins.path`)
266
+ fall back to **Settings → Plugins → ⚙ → Install Plugin from Disk**. Each IDE, stable and EAP
267
+ build keeps its own plugins. Classic and remote terminals are not supported yet.
268
+ See [plugin details](plugins/jetbrains/README.md) for installation and build instructions.
269
+
270
+ ### VS Code terminal jump
271
+
272
+ VS Code 1.80+ and its forks (Cursor, Windsurf, VSCodium, Insiders, etc.) jump to the exact
273
+ integrated terminal — in the panel, a split or the editor area — through the **CC Pets Terminal**
274
+ extension. In **Settings → General → Terminal Jump**, each detected app has its own row;
275
+ **Install** runs that app's own command line tool with the bundled VSIX after you confirm.
276
+ Open windows usually connect on their own; otherwise run **Developer: Reload Window**. Apps
277
+ without a command line tool fall back to **Extensions → ⋯ → Install from VSIX…**. Without the
278
+ extension, a card only brings the app forward. Remote windows (SSH, WSL, containers) are not
279
+ supported. See [extension details](plugins/vscode/README.md).
280
+
281
+ ### Codex and Claude hooks
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
+
201
288
  Codex Hooks and Claude Code Hooks drive the pet's agent-state animations. After a
202
289
  first installation or a Codex Hook update, start Codex and run `/hooks` to review
203
290
  and trust the CC Pets Hook. Codex skips untrusted user hooks.
204
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
+
205
300
  The Claude Code integration merges into `~/.claude/settings.json` while preserving
206
301
  existing `env`, `model`, `statusLine`, and hook settings. Its quota collector is
207
302
  injected into the existing status line script without changing the configured
@@ -233,8 +328,7 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
233
328
  ```
234
329
 
235
330
  <p align="center">
236
- <img src="docs/images/main-menu-overview.en.png" width="45%" alt="Main menu Overview page with the pet, today's token usage and quota cards for each account">
237
- <img src="docs/images/main-menu-usage.en.png" width="45%" alt="Main menu Usage page with a 30-day daily chart stacked by model and a per-model table">
331
+ <img src="docs/images/main-menu-overview.en.png" width="48%" alt="Main menu Overview page with the pet, today's token usage and quota cards for each account"> <img src="docs/images/main-menu-usage.en.png" width="48%" alt="Main menu Usage page with a 30-day daily chart stacked by model and a per-model table">
238
332
  </p>
239
333
 
240
334
  - **Sidebar** — the current pet, animated, with its status, then two groups: **Workbench**
@@ -257,15 +351,15 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
257
351
  an inbox and recent deliveries. Only who sent what to whom is shown, never the message.
258
352
  - **Usage** — local Claude Code and Codex token usage for the last 7, 30 or 90 days. The same
259
353
  five numbers as the overview lead the page: total usage (input + cache write + output +
260
- cached input), input, output, cached input with its hit rate, and requests. The daily bar
354
+ cached input + background usage), input, output, cached input with its hit rate, and requests. Background usage from local Codex SQLite logs contributes to the total only, without an inferred token breakdown. The daily bar
261
355
  chart stacks models in fixed colors and can switch between those five measures; click a model in the legend or the table to see only that
262
356
  model, and hover a bar for that day's numbers. Everything is counted from local session
263
357
  logs; nothing is sent anywhere. A per-day archive keeps history after Claude Code prunes
264
358
  old transcripts.
265
359
  - **Multi-Account** — add Claude / Codex Homes, view paths and integration status, and manage repairs, names, relocation and removal of custom Home integrations.
266
360
  - **Pet / Alerts / Settings** — every pet setting, split into three short pages (Pet:
267
- picker, size, chatter, click reactions and Codex import; Alerts: notifications, the status
268
- card and system status; Settings: language, panel appearance and the pet sprites folder), plus finer controls such as the click-reaction thresholds and a
361
+ picker, deletion of unselected custom pets with confirmation, size, chatter, click reactions and Codex import; Alerts: notifications, the status
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
269
363
  continuous glass dimming slider (the menu keeps its four presets). Changes apply to the
270
364
  desktop pet immediately, and changes made in the menu show up here. Options that rewrite
271
365
  Claude Code / Codex configuration (enabling CC Bridge, auto-approve) stay in the
@@ -274,7 +368,10 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
274
368
  - **Diagnostics** — the same checks as `cc-pets doctor`, problems first: each with its area,
275
369
  the suggested fix command and a copy button. Passing checks fold into one line. The PATH
276
370
  order check only points you to `cc-pets doctor` in a terminal, since the pet's own PATH
277
- isn't your terminal's.
371
+ isn't your terminal's. Version checks compare the local package, running binary and installed App;
372
+ source checkouts are labeled as a local source package, npm installations as a local npm package,
373
+ and unrecognized locations as a local package. These labels do not indicate publication on npm;
374
+ the update checker queries published versions separately.
278
375
  **Re-check** and **Copy Report** (paths are shown as `~`, so it is safe to paste into an
279
376
  issue). Registered accounts' Hooks and Claude status line issues offer **Auto-fix** and
280
377
  **Fix All**. Configuration and affected scripts are backed up before changes, then checks
@@ -282,9 +379,42 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
282
379
  `manifest.json` records original paths, permissions and backup files. Other issues retain
283
380
  their manual commands. Plain `cc-pets doctor` remains read-only.
284
381
 
285
- The window is created when you open it and released when you close it, and nothing runs in
286
- the background while it is closed. The Dock icon and menu bar appear only while it is open;
287
- 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.
288
418
 
289
419
  ## Pet interaction
290
420
 
@@ -309,8 +439,7 @@ default. Changes apply immediately to the quota panel, status card, and speech
309
439
  bubble, and persist across restarts. Liquid Glass uses native system glass and is
310
440
  available on macOS 26 and later only. Building native glass support requires the
311
441
  macOS 26 SDK or later. The same submenu has a **Glass dimming** setting for the quota
312
- panel, status card, and speech bubble: Clear (0%), Light (15%), Standard (25%,
313
- default), or Legible (45%). Lower levels
442
+ panel, status card, and speech bubble: Clear (0%), Light (25%), Standard (50%), or Legible (100%). Lower levels
314
443
  look more transparent; higher levels keep text readable over light backgrounds.
315
444
 
316
445
  ### Language
@@ -373,8 +502,17 @@ Local seven-day quota history is disabled by default. When enabled, it is stored
373
502
  only at `~/Library/Application Support/CC Pets/quota-history.json`, retains seven
374
503
  days, and records at most once every 15 minutes.
375
504
 
505
+ In API usage mode, the monthly token trend shows today's usage and recorded days on
506
+ separate lines; hover over it for the selected account's peak usage. Codex exhaustion
507
+ markers expire five minutes after sampling, including when recovered from cache.
508
+
376
509
  ## Speech
377
510
 
511
+ Low-quota reminders track subscription accounts independently at 20%, 10% and 5%
512
+ remaining, name the triggering account, and queue during cooldown. Initial samples,
513
+ expired windows and API-usage accounts do not trigger reminders. General quota
514
+ placeholders use the subscription account with the least remaining quota.
515
+
378
516
  The pet's speech comes from `~/.cc-pets/speech.txt`. Open **Chatter → Edit Lines…**
379
517
  on the window's **Pet** page to edit, validate, preview, or restore it. Lines are grouped
380
518
  under stable situation tags such as `[idle]`, `[done]`, and `[state_thinking]`.
@@ -451,12 +589,15 @@ external assets.
451
589
 
452
590
  ## Privacy
453
591
 
592
+ - Optional Shadowrocket launch protection (off by default) checks the local VPN state and sends HTTPS requests to the configured service’s `/cdn-cgi/trace` endpoint. The endpoint sees the connection’s exit IP; probes send no account credentials, verify TLS and do not follow redirects. See [Shadowrocket launch check](#shadowrocket-launch-check) for routing and support limits.
593
+ - Token accounting also reads local Codex SQLite logs and thread metadata, and keeps derived usage totals and incremental-read cursors in local caches; it does not upload those logs.
594
+ - Installed terminal extensions listen only on `127.0.0.1` and authenticate local requests. They store instance metadata and a local access token in `~/Library/Application Support/CC Pets/ide-instances/` with owner-only permissions. Extension installation writes to the selected IDE’s plugin/extension directory after confirmation; scripted terminal jumps require macOS Automation permission.
454
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.
455
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.
456
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.
457
- - Hooks write only redacted state events and quota cache files to the current user's temporary directory.
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.
458
599
  - Local quota history is disabled by default and retains seven days when enabled.
459
- - Status cards and notifications show only provider, state, and redacted tool category.
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.
460
601
  - CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
461
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.
462
603
  - Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
@@ -483,7 +624,10 @@ and restores the previous Claude status line. Other user settings and hooks rema
483
624
  CC Pets is a community open-source project with no affiliation, authorization, or
484
625
  official partnership with OpenAI, Anthropic, PetDex, or any character rights holder.
485
626
  Codex, ChatGPT, Claude, their icons, and their trademarks belong to their respective
486
- owners.
627
+ owners. When installed application icons are unavailable, CC Pets uses bundled Claude
628
+ and Codex fallback icons with normalized sizing. Their sources and separate ownership
629
+ are documented in [Third-party notices](./THIRD_PARTY_NOTICES.md); these icons are not
630
+ covered by the project's MIT License.
487
631
 
488
632
  ## License
489
633