cc-pets 2.4.0 → 2.6.0-beta.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 +93 -14
- package/CC_BRIDGE.zh-CN.md +71 -11
- 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 +116 -34
- package/README.zh-CN.md +99 -35
- package/Resources/AgentIcons/antigravity.icns +0 -0
- package/Resources/zh-Hans.lproj/Localizable.strings +99 -26
- package/Sources/CCPets/App/CCPetsAppDelegate+AgentEvents.m +51 -4
- package/Sources/CCPets/App/CCPetsAppDelegate+AgentStatus.m +120 -17
- package/Sources/CCPets/App/CCPetsAppDelegate+Bridge.m +24 -11
- package/Sources/CCPets/App/CCPetsAppDelegate+MenuBar.m +86 -0
- package/Sources/CCPets/App/CCPetsAppDelegate+Private.h +24 -1
- package/Sources/CCPets/App/CCPetsAppDelegate+Profiles.m +21 -11
- package/Sources/CCPets/App/CCPetsAppDelegate+Quota.m +33 -17
- package/Sources/CCPets/App/CCPetsAppDelegate+Settings.m +43 -7
- package/Sources/CCPets/App/CCPetsAppDelegate+Speech.m +7 -4
- package/Sources/CCPets/App/CCPetsAppDelegate+Update.m +7 -4
- package/Sources/CCPets/App/CCPetsAppDelegate+Workbench.m +24 -22
- package/Sources/CCPets/App/CCPetsAppDelegate.h +10 -0
- package/Sources/CCPets/App/CCPetsAppDelegate.m +18 -8
- package/Sources/CCPets/App/CCPetsVersion.h +4 -0
- package/Sources/CCPets/App/CCPetsVersion.m +34 -0
- package/Sources/CCPets/App/main.m +11 -0
- package/Sources/CCPets/Bridge/CCPetsBridge.m +41 -17
- package/Sources/CCPets/Bridge/CCPetsBridgeAntigravityApp.h +4 -0
- package/Sources/CCPets/Bridge/CCPetsBridgeAntigravityApp.m +119 -0
- package/Sources/CCPets/Bridge/CCPetsBridgeCLI.h +3 -1
- package/Sources/CCPets/Bridge/CCPetsBridgeCLI.m +272 -50
- package/Sources/CCPets/Bridge/CCPetsBridgeCore.h +12 -3
- package/Sources/CCPets/Bridge/CCPetsBridgeCore.m +341 -95
- package/Sources/CCPets/Bridge/CCPetsBridgeSetup.h +0 -2
- package/Sources/CCPets/Bridge/CCPetsBridgeSetup.m +227 -95
- package/Sources/CCPets/Bridge/CCPetsBridgeStore.h +35 -5
- package/Sources/CCPets/Bridge/CCPetsBridgeStore.m +310 -42
- package/Sources/CCPets/Bridge/CCPetsBridgeTerminalTitle.h +12 -0
- package/Sources/CCPets/Bridge/CCPetsBridgeTerminalTitle.m +105 -0
- package/Sources/CCPets/Integrations/CCPetsAntigravityConfig.h +17 -0
- package/Sources/CCPets/Integrations/CCPetsAntigravityConfig.m +462 -0
- package/Sources/CCPets/Integrations/CCPetsAntigravityEvents.h +5 -0
- package/Sources/CCPets/Integrations/CCPetsAntigravityEvents.m +180 -0
- package/Sources/CCPets/Integrations/CCPetsBridgeTitleRelay.h +3 -0
- package/Sources/CCPets/Integrations/CCPetsBridgeTitleRelay.m +463 -0
- package/Sources/CCPets/Integrations/CCPetsEvents.h +5 -0
- package/Sources/CCPets/Integrations/CCPetsEvents.m +68 -12
- package/Sources/CCPets/Integrations/CCPetsIntegrations.h +1 -1
- package/Sources/CCPets/Integrations/CCPetsIntegrations.m +38 -8
- package/Sources/CCPets/Integrations/CCPetsLaunchPreflight.m +15 -5
- package/Sources/CCPets/Integrations/CCPetsProfiles.h +2 -1
- package/Sources/CCPets/Integrations/CCPetsProfiles.m +112 -81
- package/Sources/CCPets/Integrations/CCPetsTerminalFocus.h +11 -1
- package/Sources/CCPets/Integrations/CCPetsTerminalFocus.m +217 -45
- package/Sources/CCPets/Pet/CCPetsPhrasesEditor.m +7 -0
- package/Sources/CCPets/Pet/CCPetsPreviews.m +16 -8
- package/Sources/CCPets/Pet/PetView+Menu.m +64 -5
- package/Sources/CCPets/Pet/PetView.h +7 -0
- package/Sources/CCPets/Pet/PetView.m +12 -1
- package/Sources/CCPets/Support/CCPetsDoctor.m +126 -37
- package/Sources/CCPets/Support/CCPetsPaths.h +5 -0
- package/Sources/CCPets/Support/CCPetsPaths.m +15 -0
- package/Sources/CCPets/Support/CCPetsPreferences.h +14 -1
- package/Sources/CCPets/Support/CCPetsPreferences.m +36 -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 +533 -0
- package/Sources/CCPets/UI/CCPetsMenuBarSummary.h +51 -0
- package/Sources/CCPets/UI/CCPetsMenuBarSummary.m +98 -0
- package/Sources/CCPets/UI/CCPetsSettingsPage.h +7 -1
- package/Sources/CCPets/UI/CCPetsSettingsPage.m +205 -8
- package/Sources/CCPets/UI/CCPetsStatusItem.h +28 -0
- package/Sources/CCPets/UI/CCPetsStatusItem.m +147 -0
- package/Sources/CCPets/UI/CCPetsUIStyle.m +3 -1
- package/Sources/CCPets/UI/CCPetsUsagePage.h +4 -3
- package/Sources/CCPets/UI/CCPetsUsagePage.m +69 -43
- package/Sources/CCPets/UI/CCPetsUsageStore.m +11 -1
- package/Sources/CCPets/UI/CCPetsWorkbenchPages.m +6 -4
- package/Sources/CCPets/Usage/CCPetsAntigravityQuota.m +115 -0
- package/Sources/CCPets/Usage/CCPetsNormalizedUsage.h +5 -0
- package/Sources/CCPets/Usage/CCPetsNormalizedUsage.m +43 -0
- package/Sources/CCPets/Usage/CCPetsProviderRegistry+Testing.h +13 -0
- package/Sources/CCPets/Usage/CCPetsProviderRegistry.h +25 -0
- package/Sources/CCPets/Usage/CCPetsProviderRegistry.m +94 -0
- package/Sources/CCPets/Usage/CCPetsQuotaHistory.h +1 -1
- package/Sources/CCPets/Usage/CCPetsQuotaHistory.m +11 -8
- package/Sources/CCPets/Usage/CCPetsUsage+Internal.h +2 -0
- package/Sources/CCPets/Usage/CCPetsUsage+Models.m +206 -14
- package/Sources/CCPets/Usage/CCPetsUsage+TokenTotals.m +4 -4
- package/Sources/CCPets/Usage/CCPetsUsage.h +7 -2
- package/Sources/CCPets/Usage/CCPetsUsageMode.h +2 -0
- package/Sources/CCPets/Usage/CCPetsUsageMode.m +29 -4
- package/Sources/CCPets/Usage/CCPetsUsageMonitor.h +4 -4
- package/Sources/CCPets/Usage/CCPetsUsageMonitor.m +90 -7
- package/Sources/CCPets/Usage/QuotaDashboardView+CompactRow.m +81 -0
- package/Sources/CCPets/Usage/QuotaDashboardView+Primitives.m +5 -8
- package/Sources/CCPets/Usage/QuotaDashboardView+Private.h +26 -4
- package/Sources/CCPets/Usage/QuotaDashboardView+Rendering.m +99 -99
- package/Sources/CCPets/Usage/QuotaDashboardView.h +9 -10
- package/Sources/CCPets/Usage/QuotaDashboardView.m +232 -79
- package/THIRD_PARTY_NOTICES.md +5 -4
- package/THIRD_PARTY_NOTICES.zh-CN.md +6 -5
- package/bin/agy-with-pet +82 -0
- package/bin/cc-pets +1 -1
- package/bin/claude-with-pet +15 -0
- package/bin/codex-with-pet +17 -2
- package/package.json +5 -3
- package/scripts/install-shell-integration.sh +5 -0
package/README.md
CHANGED
|
@@ -1,28 +1,26 @@
|
|
|
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
|
|
6
6
|
|
|
7
7
|
English | [简体中文](./README.zh-CN.md)
|
|
8
8
|
|
|
9
|
-
A native macOS desktop pet for Codex
|
|
10
|
-
|
|
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.
|
|
9
|
+
A native macOS desktop pet for Codex, Claude Code, and Antigravity CLI. Launch CC Pets
|
|
10
|
+
directly or start a supported CLI to see session activity, quota, and local token usage.
|
|
13
11
|
|
|
14
12
|
> The app and CLI are available in English and Simplified Chinese (see [Language](#language)).
|
|
15
13
|
|
|
16
|
-
## What's new in v2.
|
|
14
|
+
## What's new in v2.5.0
|
|
17
15
|
|
|
18
|
-
- **
|
|
19
|
-
|
|
20
|
-
- **
|
|
21
|
-
|
|
22
|
-
- **
|
|
23
|
-
|
|
16
|
+
- **Menu bar mode** — keep the pet, add a menu bar panel, or use the menu bar alone;
|
|
17
|
+
check sessions and quota, and jump straight to a terminal awaiting approval.
|
|
18
|
+
- **Clearer sessions** — identify status cards by session, track persistent Codex
|
|
19
|
+
desktop chats, and clear ended sessions without replaying completion animations.
|
|
20
|
+
- **CC Bridge reliability** — identify shared-host callers per tool call, improve
|
|
21
|
+
concurrent file reservations and message cleanup, and preserve unrelated config.
|
|
24
22
|
|
|
25
|
-
See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
23
|
+
See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.5.0.md) for the full list.
|
|
26
24
|
|
|
27
25
|
## Screenshots
|
|
28
26
|
|
|
@@ -34,9 +32,9 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
|
34
32
|
|
|
35
33
|
- Supports English and Simplified Chinese in the app and CLI, with live UI language switching.
|
|
36
34
|
- Offers Classic and native Liquid Glass panel themes on macOS 26 and later.
|
|
37
|
-
- Starts with Codex
|
|
38
|
-
- Shares one pet across
|
|
39
|
-
- Shows five-hour and weekly remaining quota, reset times, local token
|
|
35
|
+
- Starts with Codex, Claude Code, or Antigravity CLI and closes when the last CLI launched through CC Pets exits, unless Codex or Antigravity desktop is still running.
|
|
36
|
+
- Shares one pet across simultaneous sessions from supported CLIs.
|
|
37
|
+
- Shows five-hour and weekly remaining quota, reset times, local token counts, and seven-day trends in the hover panel.
|
|
40
38
|
- Converts reset times to the Mac's current system time zone.
|
|
41
39
|
- Responds to thinking, tool, approval, subagent, completion, and failure events.
|
|
42
40
|
- Displays a redacted glass status card with the active CLI session count.
|
|
@@ -53,6 +51,7 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
|
53
51
|
selection persists across pet changes and restarts, with pet-specific lines selected initially.
|
|
54
52
|
- Includes one original pet and can download compatible assets from PetDex.
|
|
55
53
|
- 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)).
|
|
54
|
+
- 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
55
|
- Uses native AppKit with no Electron runtime.
|
|
57
56
|
|
|
58
57
|
## Requirements
|
|
@@ -60,7 +59,7 @@ See the [changelog](./CHANGELOG.md) and [release notes](./docs/release-notes-v2.
|
|
|
60
59
|
- macOS 13 or later
|
|
61
60
|
- Node.js 18 or later, for npm only: it installs and updates CC Pets, while the app and
|
|
62
61
|
its `cc-pets` commands, hooks and CC Bridge run natively
|
|
63
|
-
-
|
|
62
|
+
- A configured copy of Codex, Claude Code, or Antigravity CLI (`agy`)
|
|
64
63
|
- zsh
|
|
65
64
|
- Xcode Command Line Tools (`xcode-select --install`)
|
|
66
65
|
|
|
@@ -74,10 +73,12 @@ npm install -g cc-pets@latest --allow-scripts=cc-pets
|
|
|
74
73
|
codex
|
|
75
74
|
# or
|
|
76
75
|
claude
|
|
76
|
+
# or
|
|
77
|
+
agy
|
|
77
78
|
```
|
|
78
79
|
|
|
79
80
|
The `--allow-scripts=cc-pets` option allows recent npm versions to run the
|
|
80
|
-
package's `postinstall`. That step builds the native app, installs
|
|
81
|
+
package's `postinstall`. That step builds the native app, installs the supported hook
|
|
81
82
|
integrations, configures shell shims, and installs `~/Applications/CC Pets.app`.
|
|
82
83
|
If npm installed the package without running its scripts, initialize it manually:
|
|
83
84
|
|
|
@@ -122,10 +123,12 @@ cc-pets install
|
|
|
122
123
|
codex
|
|
123
124
|
# or
|
|
124
125
|
claude
|
|
126
|
+
# or
|
|
127
|
+
agy
|
|
125
128
|
```
|
|
126
129
|
|
|
127
|
-
CC Pets installs `cc-pets`, `codex-with-pet`, and `
|
|
128
|
-
`codex` and `
|
|
130
|
+
CC Pets installs `cc-pets`, `codex-with-pet`, `claude-with-pet`, and `agy-with-pet`. It creates
|
|
131
|
+
`codex`, `claude`, and `agy` shims under `~/.cc-pets/shims` and adds one marked block to
|
|
129
132
|
`~/.zshrc`; the real CLI binaries are not replaced. The shims also handle casing
|
|
130
133
|
variants on the default case-insensitive macOS filesystem.
|
|
131
134
|
|
|
@@ -134,6 +137,7 @@ If a real CLI is not on the current `PATH`, set its absolute path:
|
|
|
134
137
|
```bash
|
|
135
138
|
export CODEX_REAL_BIN=/absolute/path/to/codex
|
|
136
139
|
export CLAUDE_REAL_BIN=/absolute/path/to/claude
|
|
140
|
+
export AGY_REAL_BIN=/absolute/path/to/agy
|
|
137
141
|
```
|
|
138
142
|
|
|
139
143
|
The wrappers pass the current terminal environment through unchanged. They do not
|
|
@@ -141,14 +145,21 @@ load or execute `.env` files.
|
|
|
141
145
|
|
|
142
146
|
## Multi-Account
|
|
143
147
|
|
|
144
|
-
CC Pets automatically detects and integrates the official `~/.claude
|
|
145
|
-
`~/.
|
|
148
|
+
CC Pets automatically detects and integrates the official `~/.claude`, `~/.codex`, and
|
|
149
|
+
`~/.gemini` Homes for installed CLIs. Custom Homes such as `~/.claude-x` or `~/.codex-work` are never
|
|
146
150
|
scanned automatically: add them explicitly from **Main menu → Multi-Account**.
|
|
147
151
|
The folder name is used as the account name by default and is preserved exactly;
|
|
148
152
|
you can rename an account from its Manage menu on the same page. Each provider has its own
|
|
149
153
|
circular quota-card carousel, and the Usage page can filter local token history
|
|
150
154
|
by account.
|
|
151
155
|
|
|
156
|
+
An Antigravity Home is the Gemini root that contains `antigravity-cli/`. After adding a custom
|
|
157
|
+
root in Multi-Account, use it when opening a session with `agy`.
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
CC_PETS_ANTIGRAVITY_HOME=/absolute/path/to/gemini-root agy
|
|
161
|
+
```
|
|
162
|
+
|
|
152
163
|
Pet Hooks and usage collection are configured when an account is added. If CC
|
|
153
164
|
Bridge is already enabled, its Hooks, permissions, and MCP registration are also
|
|
154
165
|
configured immediately; otherwise they are added automatically when CC Bridge is
|
|
@@ -161,7 +172,9 @@ Each proxy app has its own preference; Shadowrocket is the first supported optio
|
|
|
161
172
|
CC Pets wrappers require a connected Shadowrocket VPN and a valid exit IP / region from
|
|
162
173
|
the service's HTTPS `/cdn-cgi/trace` endpoint before starting Claude / Codex. Failures
|
|
163
174
|
print a reason and return a nonzero exit code before registering a session or sending
|
|
164
|
-
a starting event. Disabling the option skips all network checks.
|
|
175
|
+
a starting event. Disabling the option skips all network checks. For `agy`, only the
|
|
176
|
+
Shadowrocket connection is checked: Google's service domains have no `/cdn-cgi/trace`
|
|
177
|
+
endpoint, so the exit region can't be verified.
|
|
165
178
|
|
|
166
179
|
Claude defaults to `api.anthropic.com`. Codex uses the current Home's `auth.json` to select
|
|
167
180
|
`chatgpt.com` for ChatGPT login or `api.openai.com` for API-key login. If the mode is unknown
|
|
@@ -194,10 +207,18 @@ configuration, not just its running process. Original CLI binaries and desktop c
|
|
|
194
207
|
|
|
195
208
|
## CC Bridge
|
|
196
209
|
|
|
197
|
-
[CC Bridge](./CC_BRIDGE.md) is optional and off by default. It lets local Claude Code
|
|
198
|
-
and
|
|
210
|
+
[CC Bridge](./CC_BRIDGE.md) is optional and off by default. It lets local Claude Code,
|
|
211
|
+
Codex, and Antigravity CLI sessions exchange messages and reserve files. Antigravity's native
|
|
212
|
+
`agy` interface reads messages on its next model invocation. [Antigravity App](./CC_BRIDGE.md#antigravity-app)
|
|
213
|
+
supports automatic wake-up when its Sidecar is enabled. Session IDs are validated;
|
|
199
214
|
PID fallback is accepted only for a unique live session. Ambiguous shared-host identities
|
|
200
215
|
are rejected rather than guessed. Codex delivery uses the recipient's Home.
|
|
216
|
+
For Codex sessions sharing an app-server PID, agents pass the current `session_id` from
|
|
217
|
+
Bridge hook context on each MCP call. Reconnect MCP after updating to load the new tool definitions.
|
|
218
|
+
|
|
219
|
+
In Chinese, generated session names include an animal alias for readability; use the
|
|
220
|
+
original name or ref when addressing messages. Transient Codex tasks without persisted
|
|
221
|
+
transcripts are not registered as recipients, but still receive file reservation checks.
|
|
201
222
|
|
|
202
223
|
Unconfirmed inbox messages are recoverable after a crash. A crash between output and
|
|
203
224
|
confirmation may repeat the same message ID; delivery does not mean the recipient has
|
|
@@ -236,6 +257,7 @@ cc-pets uninstall-app # Remove only ~/Applications/CC Pets.app.
|
|
|
236
257
|
|
|
237
258
|
codex-with-pet # Start the pet and enter Codex CLI.
|
|
238
259
|
claude-with-pet # Start the pet and enter Claude Code CLI.
|
|
260
|
+
agy-with-pet # Start the pet and enter Antigravity CLI.
|
|
239
261
|
```
|
|
240
262
|
|
|
241
263
|
`package.json` is the single version source. Use `npm version patch`, `minor`, or
|
|
@@ -271,17 +293,37 @@ without a command line tool fall back to **Extensions → ⋯ → Install from V
|
|
|
271
293
|
extension, a card only brings the app forward. Remote windows (SSH, WSL, containers) are not
|
|
272
294
|
supported. See [extension details](plugins/vscode/README.md).
|
|
273
295
|
|
|
274
|
-
###
|
|
296
|
+
### Agent hooks
|
|
297
|
+
|
|
298
|
+
Status card titles show the session and its state. Generated CC Bridge names use the
|
|
299
|
+
short `directory.animal` form; custom names are preserved. Without a Bridge name, the
|
|
300
|
+
card uses the working directory name, falling back to the agent name. Hover to see
|
|
301
|
+
the full session name and working directory. Long titles retain the animal suffix.
|
|
275
302
|
|
|
276
303
|
Codex Hooks and Claude Code Hooks drive the pet's agent-state animations. After a
|
|
277
304
|
first installation or a Codex Hook update, start Codex and run `/hooks` to review
|
|
278
305
|
and trust the CC Pets Hook. Codex skips untrusted user hooks.
|
|
279
306
|
|
|
307
|
+
Persistent Codex desktop chats also appear in the session list and online counts while
|
|
308
|
+
their app instance is running. Transient background tasks are excluded. Restarting CC Pets
|
|
309
|
+
can restore recent desktop records without replaying animations or notifications; unfinished
|
|
310
|
+
states return as idle. A session-end event removes the chat and switches to another live
|
|
311
|
+
session or returns the pet to idle, without a completion animation. Without an end event,
|
|
312
|
+
a desktop chat may remain listed until its app exits. Desktop start events do not play
|
|
313
|
+
the CLI startup animation.
|
|
314
|
+
|
|
280
315
|
The Claude Code integration merges into `~/.claude/settings.json` while preserving
|
|
281
316
|
existing `env`, `model`, `statusLine`, and hook settings. Its quota collector is
|
|
282
317
|
injected into the existing status line script without changing the configured
|
|
283
318
|
script path or output.
|
|
284
319
|
|
|
320
|
+
The Antigravity CLI integration uses global Gemini hooks for the status card, approval and stall
|
|
321
|
+
reminders, the Main menu, the menu bar and notifications, matching Claude and Codex. Antigravity
|
|
322
|
+
App conversations share the same hooks, appear as "Antigravity App" and focus the App when
|
|
323
|
+
clicked. Approval state is available for the CLI only. Use `agy` to keep the native terminal UI and `agy-with-pet` to
|
|
324
|
+
invoke the launcher explicitly. `cc-pets doctor` checks the launcher, hooks and Bridge MCP
|
|
325
|
+
registration, and `cc-pets paths` lists their configuration files.
|
|
326
|
+
|
|
285
327
|
Third-party CLI agents can send redacted state events through standard input:
|
|
286
328
|
|
|
287
329
|
```bash
|
|
@@ -329,17 +371,17 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
|
|
|
329
371
|
- **Sessions** — the Agent sessions online right now (sessions waiting for
|
|
330
372
|
approval first, each with **Go to Terminal**) and CC Bridge traffic: messages waiting in
|
|
331
373
|
an inbox and recent deliveries. Only who sent what to whom is shown, never the message.
|
|
332
|
-
- **Usage** — local Claude Code and
|
|
374
|
+
- **Usage** — local Claude Code, Codex, Antigravity CLI, and Antigravity App token usage for the last 7, 30 or 90 days. The All view includes every source, and Antigravity CLI and App each have a separate filter. The same
|
|
333
375
|
five numbers as the overview lead the page: total usage (input + cache write + output +
|
|
334
376
|
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
|
|
335
377
|
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
|
|
336
378
|
model, and hover a bar for that day's numbers. Everything is counted from local session
|
|
337
379
|
logs; nothing is sent anywhere. A per-day archive keeps history after Claude Code prunes
|
|
338
380
|
old transcripts.
|
|
339
|
-
- **Multi-Account** — add Claude
|
|
381
|
+
- **Multi-Account** — add Claude, Codex, or Antigravity CLI Homes, view paths and integration status, and manage repairs, names, relocation and removal of custom Home integrations.
|
|
340
382
|
- **Pet / Alerts / Settings** — every pet setting, split into three short pages (Pet:
|
|
341
383
|
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
|
|
384
|
+
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
385
|
continuous glass dimming slider (the menu keeps its four presets). Changes apply to the
|
|
344
386
|
desktop pet immediately, and changes made in the menu show up here. Options that rewrite
|
|
345
387
|
Claude Code / Codex configuration (enabling CC Bridge, auto-approve) stay in the
|
|
@@ -359,9 +401,42 @@ cc-pets open general # also: pet, accounts, alerts, diagnostics
|
|
|
359
401
|
`manifest.json` records original paths, permissions and backup files. Other issues retain
|
|
360
402
|
their manual commands. Plain `cc-pets doctor` remains read-only.
|
|
361
403
|
|
|
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.
|
|
404
|
+
The Main menu window is created when you open it and released when you close it; its pages
|
|
405
|
+
do not run background tasks while closed. The Dock icon and application menus appear only
|
|
406
|
+
while the window is open; clicking the Dock icon brings a minimized window back. The optional
|
|
407
|
+
menu bar status icon follows Settings → Show In independently of this window.
|
|
408
|
+
|
|
409
|
+
### Menu bar
|
|
410
|
+
|
|
411
|
+
**Main menu → Settings → Show In** chooses where CC Pets appears: **Desktop Pet** (default),
|
|
412
|
+
**Pet + Menu Bar**, or **Menu Bar Only**. With a menu bar icon:
|
|
413
|
+
|
|
414
|
+
- **Left-click** opens a compact glass panel in the same style as the hover panel: the pet and
|
|
415
|
+
what it is doing, up to five online sessions (awaiting approval first; click one to jump to
|
|
416
|
+
its terminal), one row per account with a 5-hour quota ring, weekly quota left and the next
|
|
417
|
+
reset (API accounts show this month's tokens and calls; plan accounts are listed first), today's total tokens, **Show Pet**
|
|
418
|
+
and **Main menu**. When an update is available, **Update to x.y.z…** appears here too. Trends,
|
|
419
|
+
token breakdowns and system status stay in the hover panel and the Main menu. Click outside
|
|
420
|
+
the panel or press Esc to close it.
|
|
421
|
+
- **While a session awaits approval**, left-click jumps straight to its terminal instead (the
|
|
422
|
+
first one in the session list, so the next click goes to the next one). ⌥-click still opens
|
|
423
|
+
the panel, and the panel opens as usual when that session's terminal can't be resolved.
|
|
424
|
+
- **Right-click** (or Control-click) opens the same menu as right-clicking the pet, including
|
|
425
|
+
the CC Bridge switches and **Quit**.
|
|
426
|
+
- The icon is an outlined terminal window with a `>_` prompt that takes the status card's color:
|
|
427
|
+
normal menu bar color while idle, blue while an agent works, green after a task completes and
|
|
428
|
+
red after a failure. Awaiting approval, the only state that needs you, shows orange `•••`. It returns to the normal
|
|
429
|
+
menu bar color when the status card goes back to idle (about a minute without new events),
|
|
430
|
+
so Hook activity stays visible even with the pet hidden.
|
|
431
|
+
- The icon shows a red count of sessions awaiting approval. **Quota in Menu Bar** adds the
|
|
432
|
+
lowest 5-hour quota left among plan accounts, in orange at 20% or below and red at 10%. With
|
|
433
|
+
the switch off no number is shown, even when quota is low.
|
|
434
|
+
|
|
435
|
+
**Menu Bar Only** hides the pet, its status card, speech bubbles, update bubble and hover
|
|
436
|
+
panel. Chatter is skipped without using up its hourly budget, so low-quota warnings are only
|
|
437
|
+
visible as the menu bar color. Agent tracking, quota collection and system notifications keep
|
|
438
|
+
running. The icon goes away with the pet when the last managed CLI exits, unless
|
|
439
|
+
Codex desktop is still running. Standalone launches stay open until you quit.
|
|
365
440
|
|
|
366
441
|
## Pet interaction
|
|
367
442
|
|
|
@@ -445,6 +520,13 @@ The persistent app reads `~/.codex` and `~/.claude` by default instead of inheri
|
|
|
445
520
|
session-specific `CODEX_HOME` or `CLAUDE_CONFIG_DIR` values. Advanced users can
|
|
446
521
|
override these with `CC_PETS_CODEX_HOME` and `CC_PETS_CLAUDE_CONFIG_DIR`.
|
|
447
522
|
|
|
523
|
+
Antigravity CLI reads local transcripts from `~/.gemini/antigravity-cli/brain`, or from the registered
|
|
524
|
+
CLI Home. Antigravity App reads the separate transcript folder at `~/.gemini/antigravity/brain`.
|
|
525
|
+
CC Pets displays the two sets of Token and request counts separately. The hover panel also shows
|
|
526
|
+
Antigravity alongside Codex and Claude, with its display mode under Hover Panel in Settings. CC Pets reads subscription quota
|
|
527
|
+
for each signed-in account through `agy -p /usage --output-format json` and displays the available
|
|
528
|
+
five-hour and weekly windows once per account. API-key mode displays local usage.
|
|
529
|
+
|
|
448
530
|
Local seven-day quota history is disabled by default. When enabled, it is stored
|
|
449
531
|
only at `~/Library/Application Support/CC Pets/quota-history.json`, retains seven
|
|
450
532
|
days, and records at most once every 15 minutes.
|
|
@@ -542,9 +624,9 @@ external assets.
|
|
|
542
624
|
- 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
625
|
- 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
626
|
- 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
|
|
627
|
+
- 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
628
|
- Local quota history is disabled by default and retains seven days when enabled.
|
|
547
|
-
- Status cards
|
|
629
|
+
- 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
630
|
- CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
|
|
549
631
|
- 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
632
|
- Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
|
package/README.zh-CN.md
CHANGED
|
@@ -1,24 +1,24 @@
|
|
|
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:菜单栏模式、会话展示与 CC Bridge 可靠性改进">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
# CC Pets
|
|
6
6
|
|
|
7
7
|
[English](./README.md) | 简体中文
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
一个支持 Codex、Claude Code 和 Antigravity CLI 的 macOS 原生桌宠。可以独立启动,也会随已接入的 CLI 启动,
|
|
10
|
+
显示会话状态、额度和本地 Token 用量。
|
|
11
11
|
|
|
12
|
-
## v2.
|
|
12
|
+
## v2.5.0 新功能
|
|
13
13
|
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
|
|
14
|
+
- **菜单栏模式**:保留桌宠、同时显示菜单栏或仅用菜单栏;查看会话与额度,
|
|
15
|
+
有待审批会话时可直接跳到对应终端。
|
|
16
|
+
- **会话更清楚**:状态卡按会话区分,跟踪 Codex 桌面端的持久化聊天,
|
|
17
|
+
会话结束时清理状态,不误播完成动画。
|
|
18
|
+
- **CC Bridge 可靠性**:逐次识别共享宿主上的调用者,改进并发文件预留和消息清理,
|
|
19
|
+
保留配置中不属于 Bridge 的内容。
|
|
20
20
|
|
|
21
|
-
完整改动见 [更新记录](./CHANGELOG.zh-CN.md) 和 [Release Note](./docs/release-notes-v2.
|
|
21
|
+
完整改动见 [更新记录](./CHANGELOG.zh-CN.md) 和 [Release Note](./docs/release-notes-v2.5.0.md)。
|
|
22
22
|
|
|
23
23
|
## 界面预览
|
|
24
24
|
|
|
@@ -30,9 +30,9 @@
|
|
|
30
30
|
|
|
31
31
|
- App 与 CLI 支持英语和简体中文,界面语言可即时切换
|
|
32
32
|
- macOS 26 及以上可在经典与原生 Liquid Glass 两种面板主题之间切换
|
|
33
|
-
- 随 Codex
|
|
34
|
-
-
|
|
35
|
-
-
|
|
33
|
+
- 随 Codex、Claude Code 或 Antigravity CLI 自动启动,无需打开对应桌面版
|
|
34
|
+
- 多个支持的 CLI 会话共用一个桌宠。最后一个经 CC Pets 启动的 CLI 退出后,Codex 和 Antigravity 桌面端都未运行时,桌宠自动关闭
|
|
35
|
+
- 鼠标悬停口袋时展开额度详情面板,显示 Codex、Claude 和 Antigravity 的 5 小时额度、周额度与重置时间
|
|
36
36
|
- reset 时间自动转换为 Mac 当前系统时区,例如 `Jul 22 3pm America/Los_Angeles` 在上海时区显示为 `7/23 06:00:00`
|
|
37
37
|
- 支持待机、左右拖动、身体两侧感应、头部/脚部悬停和点击反馈动画
|
|
38
38
|
- 待机呼吸、随机小动作(11 行素材会转头看鼠标)、拖动时的水平滞后与落脚回弹
|
|
@@ -50,6 +50,7 @@
|
|
|
50
50
|
- 可分别启用任务完成、失败、等待审批和响应超时的 macOS 系统通知
|
|
51
51
|
- 内置一个原创素材,更多桌宠可从兼容 PetDex 的素材源按需下载到本机
|
|
52
52
|
- 提供普通的主菜单:概览、会话与 CC Bridge 消息、按模型的 Token 用量、全部设置和内置诊断(见[主菜单](#主菜单))
|
|
53
|
+
- 可以常驻菜单栏:一键查看会话、各账号额度和今日用量,也可以完全隐藏桌宠(见[菜单栏](#菜单栏))
|
|
53
54
|
- 使用原生 AppKit,运行时不依赖 Electron
|
|
54
55
|
|
|
55
56
|
## 主菜单
|
|
@@ -77,13 +78,13 @@ cc-pets open general # 还有 pet、accounts、alerts、diagnostics
|
|
|
77
78
|
以及 Claude / Codex 的简洁账号卡片:订阅模式展示 5 小时和本周的剩余额度环、重置时间与本周节奏;API 模式展示本月调用、Token 总量,并补充日均调用及输入/输出 Token。数据与悬停面板同源。每个已登记账号独立显示一张卡片,两列排列;「查看诊断」位于名称后,仅在该账号确实有诊断问题时出现。暂未采集到额度不视为配置异常。
|
|
78
79
|
- **会话**:此刻在线的 Agent 会话(等审批的置顶,每行可「跳到终端」),以及 CC Bridge 的
|
|
79
80
|
消息往来:卡在信箱里待投递的、最近送达的。仅显示消息交互,无消息正文。
|
|
80
|
-
-
|
|
81
|
+
- **用量**统计本机 Claude Code、Codex、Antigravity CLI 和 Antigravity App 最近 7、30、90 天的 Token 用量。「全部」包含所有来源,Antigravity CLI 和 App 各有独立筛选。顶部和概览同一套五格:总用量
|
|
81
82
|
(输入 + 缓存写 + 输出 + 缓存输入 + 后台用量)、输入、输出、缓存输入(附命中率)、请求数。本机 Codex SQLite 日志补充的后台用量仅计入总量,不推算 Token 明细。每日柱状图按模型分色堆叠,
|
|
82
83
|
颜色固定跟着模型走,可以在这五项之间切换;点图例或表格里的模型只看它,鼠标移到柱子上看当天各模型的数值。
|
|
83
84
|
数据全部来自本机会话日志,不会发送到任何地方;按日归档让 Claude Code 清理旧转录之后,历史仍然留得住。
|
|
84
|
-
-
|
|
85
|
+
- **多账号**可添加 Claude、Codex 或 Antigravity CLI Home,查看目录与集成状态,并通过「管理」菜单修复、重命名、重新定位或移除自定义 Home 的集成。
|
|
85
86
|
- **宠物 / 提醒 / 设置**:桌宠的全部设置拆成三页(宠物:选宠物、确认删除未选中的自定义宠物、大小、碎碎念、点击互动、导入 Codex 素材;提醒:系统通知、桌面状态卡和系统状态;
|
|
86
|
-
|
|
87
|
+
设置:语言、显示位置、面板外观和素材目录),另有更细的项(比如连击阈值、可以连续调节的玻璃压暗,菜单里仍是四档)。
|
|
87
88
|
右键菜单只留最常用的几项:管理桌宠、宠物大小、显示消息气泡、用量展示模式、面板主题和 CC Bridge,其余都到这里改。改动会立刻作用到桌面上的宠物,在菜单里改的也会同步显示在这里。
|
|
88
89
|
会改写 Claude Code / Codex 配置的选项(启用 CC Bridge、免审批)仍只在右键菜单里。
|
|
89
90
|
- **诊断**:和 `cc-pets doctor` 同一套检查,要处理的问题置顶,每条带所属模块、修复命令和「复制命令」;
|
|
@@ -93,8 +94,30 @@ cc-pets open general # 还有 pet、accounts、alerts、diagnostics
|
|
|
93
94
|
源码 checkout/worktree 显示「本地源码包」,npm 安装显示「本地 npm 包」,无法确认来源时显示「本地包」。
|
|
94
95
|
这些标签不表示 npm 已发布该版本;线上版本由更新检查单独查询。
|
|
95
96
|
|
|
96
|
-
|
|
97
|
-
窗口最小化后点 Dock
|
|
97
|
+
主菜单窗口在打开时才创建,关闭即释放,其页面关闭后不运行后台任务。Dock 图标和应用菜单只在窗口打开期间出现,
|
|
98
|
+
窗口最小化后点 Dock 图标可以恢复。可选的菜单栏状态图标由「设置 → 显示位置」独立控制,不受主菜单窗口开关影响。
|
|
99
|
+
|
|
100
|
+
### 菜单栏
|
|
101
|
+
|
|
102
|
+
在 **主菜单 → 设置 → 显示位置** 选择 CC Pets 出现在哪里:**仅桌宠**(默认)、**桌宠 + 菜单栏**
|
|
103
|
+
或 **仅菜单栏**。有菜单栏图标时:
|
|
104
|
+
|
|
105
|
+
- **左键**打开精简的玻璃面板,风格与悬停面板一致:宠物和它此刻在做什么;最多 5 个在线会话
|
|
106
|
+
(等待审批的置顶,点一行跳到对应终端);每个账号一行,显示 5 小时额度环、本周剩余和下次重置时间
|
|
107
|
+
(API 账号显示本月 Token 和调用次数;订阅账号排在前面);今日总用量;**显示桌宠**和**主菜单**。有新版本时这里也会
|
|
108
|
+
出现「更新到 x.y.z…」。趋势、Token 明细和系统状态仍在悬停面板和主菜单里。点面板外或按 Esc 关闭。
|
|
109
|
+
- **有会话等待审批时**,左键改为直接跳到那个会话的终端(会话列表里排第一的那个,处理完再点就是下一个)。
|
|
110
|
+
按住 ⌥ 点击仍然打开面板;取不到该会话的终端时也照常打开面板。
|
|
111
|
+
- **右键**(或按住 Control 点击)打开和右键桌宠相同的菜单,CC Bridge 开关和**退出**都在里面。
|
|
112
|
+
- 图标是一个带 `>_` 提示符的描边终端窗口,颜色与状态卡同步:待机为菜单栏原色,Agent 工作中为蓝色,
|
|
113
|
+
任务完成为绿色,失败为红色。等待审批是唯一需要你动手的状态,显示为橙色 `•••`。
|
|
114
|
+
状态卡回落待机(约 1 分钟没有新事件)时恢复菜单栏原色,因此隐藏桌宠时也能看到 Hook 动态。
|
|
115
|
+
- 图标旁用红色数字显示等待审批的会话数。打开 **菜单栏显示额度** 后会附上订阅账号中最低的
|
|
116
|
+
5 小时剩余额度,20% 及以下为橙色,10% 及以下为红色;关掉开关后不显示数字,额度低时也一样。
|
|
117
|
+
|
|
118
|
+
**仅菜单栏** 会隐藏桌宠、状态卡、说话气泡、更新气泡和悬停面板。碎碎念直接跳过、不占每小时预算,
|
|
119
|
+
因此低额度提醒只剩菜单栏数字变色。Agent 状态跟踪、额度采集和系统通知照常运行。
|
|
120
|
+
最后一个托管 CLI 退出且 Codex 桌面端未运行时,菜单栏图标随桌宠一起消失;独立启动时会保持运行,直到手动退出。
|
|
98
121
|
|
|
99
122
|
## 互动方式
|
|
100
123
|
|
|
@@ -120,7 +143,7 @@ VS Code 1.80+ 及其分支(Cursor、Windsurf、VSCodium、Insiders 等)可
|
|
|
120
143
|
|
|
121
144
|
| Agent 事件 | 桌宠反馈 |
|
|
122
145
|
| --- | --- |
|
|
123
|
-
| 新会话启动 | 挥手唤醒 |
|
|
146
|
+
| CLI 新会话启动 | 挥手唤醒 |
|
|
124
147
|
| 提交用户提示、Agent 思考 | 思考动画 |
|
|
125
148
|
| 执行 Shell 命令 | 跑动动画 |
|
|
126
149
|
| 编辑或写入文件 | 工作动画 |
|
|
@@ -130,6 +153,7 @@ VS Code 1.80+ 及其分支(Cursor、Windsurf、VSCodium、Insiders 等)可
|
|
|
130
153
|
| 工具执行成功 | 完成动画 |
|
|
131
154
|
| 工具执行失败 | 失败动画 |
|
|
132
155
|
| 当前回合或子 Agent 结束 | 告别后恢复待机 |
|
|
156
|
+
| 当前会话退出 | 切换到其他在线会话或恢复待机,不播放完成动画 |
|
|
133
157
|
|
|
134
158
|
Agent 动画分别由 Codex Hooks 和 Claude Code Hooks 驱动。首次安装或 Codex Hook 内容更新后,启动 Codex 并执行
|
|
135
159
|
`/hooks`,检查并信任 CC Pets Hook;未经信任的用户级 Hook 会被 Codex 安全机制跳过。
|
|
@@ -140,11 +164,20 @@ Claude Code Hook 会合并到 `~/.claude/settings.json`,现有的 `env`、`mod
|
|
|
140
164
|
通过 npm 安装或升级时会自动重新构建应用、安装或更新两套 Hooks,并配置 shell 集成;如果旧版桌宠正在运行,
|
|
141
165
|
安装器会自动重启桌宠,使新版本生效。`cc-pets install` 用于手动修复或重新初始化。
|
|
142
166
|
|
|
167
|
+
Antigravity CLI 通过 Gemini 全局 Hooks 接入状态卡、审批提醒、卡住提醒、主菜单与菜单栏展示和系统通知,和 Claude / Codex 一致。
|
|
168
|
+
Antigravity App 的对话共用同一份 Hooks,以「Antigravity App」显示,点状态卡回到 App。审批状态只对 CLI 可用。
|
|
169
|
+
运行 `agy` 保留原生终端界面,也可以显式运行 `agy-with-pet`。`cc-pets doctor` 检查启动入口、Hooks 和 Bridge MCP,
|
|
170
|
+
`cc-pets paths` 列出配置文件的位置。
|
|
171
|
+
|
|
143
172
|
通过 `codex-with-pet` / `claude-with-pet` 启动时,包装脚本会在 Agent 启动前记录终端身份,
|
|
144
173
|
这是最精确的来源。直接运行 `codex` / `claude`、或终端窗口早于 shim 安装就已打开的会话,
|
|
145
174
|
会回退到内核信息:从进程树解析控制终端和承载终端的应用,这些会话的状态卡同样可以点击回跳。
|
|
146
175
|
这类会话没有 pid 文件,只要 Hook 还在持续发事件就会留在最近会话列表里,闲置 60 秒后移出列表。
|
|
147
176
|
|
|
177
|
+
Codex 桌面端的持久化聊天也会出现在会话列表并计入在线数量,按当前应用实例判断存活;后台临时任务不计入。
|
|
178
|
+
重启桌宠可恢复近期桌面会话记录,不重播动画或通知,未完成的状态恢复为待机。收到会话结束事件后移除该聊天,
|
|
179
|
+
并切换到其他在线会话或恢复待机;未收到结束事件时,聊天可能保留到桌面应用退出。桌面会话启动不播放 CLI 的启动动画。
|
|
180
|
+
|
|
148
181
|
所有 Hook 状态卡都可以点击;右侧圆形状态图标会展开最近 8 个在线 Agent 终端会话。
|
|
149
182
|
macOS Terminal 和 iTerm2 会按 TTY 精确选中对应标签页或 Session,Ghostty 1.4+ 还支持精确选择分屏。
|
|
150
183
|
VS Code 和 JetBrains IDE 通过随包扩展精确选择终端;未安装扩展时,以及 Warp、WezTerm 和旧版 Ghostty,
|
|
@@ -177,13 +210,14 @@ Hook 状态卡和消息气泡在宠物小于 100% 时同比例缩小,文字、
|
|
|
177
210
|
可在通透(0%)、轻度(25%)、标准(50%)、清晰(100%)之间切换,作用于额度面板、状态卡和
|
|
178
211
|
说话气泡:档位越低越通透,档位越高在浅色背景上越容易看清。
|
|
179
212
|
|
|
180
|
-
###
|
|
213
|
+
### 启动前检查 Shadowrocket
|
|
181
214
|
|
|
182
215
|
在 **主菜单 → 设置 → 启动保护** 打开「Shadowrocket」开关(默认关闭)。
|
|
183
216
|
启动保护按软件分别配置,当前提供 Shadowrocket,后续软件可在同一分组增加独立开关。
|
|
184
217
|
通过 CC Pets 包装器启动 `claude` / `codex` 时,会先确认 Shadowrocket 的系统 VPN
|
|
185
218
|
状态为已连接,再向对应服务的 `/cdn-cgi/trace` 发起 HTTPS GET,检查出口 IP 和地区;失败会在终端提示原因并返回非零退出码,
|
|
186
219
|
不会启动 CLI,也不会登记会话或发送启动事件。关闭开关后不进行网络检查。
|
|
220
|
+
`agy` 只检查 Shadowrocket 是否已连接:Google 的服务域名没有 `/cdn-cgi/trace` 这类端点,无法核验出口地区。
|
|
187
221
|
|
|
188
222
|
仅识别 Shadowrocket 的 VPN 配置,不把「应用进程正在运行」当成代理已连接。
|
|
189
223
|
Claude 默认检查 `api.anthropic.com`;Codex 根据当前 Home 的 `auth.json` 选择:ChatGPT 登录检查
|
|
@@ -256,7 +290,9 @@ Agent 状态动画会优先播放。
|
|
|
256
290
|
|
|
257
291
|
Agent 状态卡片会根据屏幕剩余空间自动显示在桌宠上方或下方。点击桌宠旁的圆形箭头可以
|
|
258
292
|
折叠卡片;折叠后圆钮会显示当前活跃的 Codex/Claude CLI 会话数,点击后重新展开。卡片只展示
|
|
259
|
-
|
|
293
|
+
会话标签、脱敏状态和通用说明,不提供消息输入,也不会显示提示词、命令正文或模型输出。
|
|
294
|
+
标题优先使用 CC Bridge 会话名:自动名称缩写为「目录名.动物」,自定义名称保持原样;
|
|
295
|
+
没有 Bridge 名称时使用工作目录名,再回退到智能体名称。长标签保留末尾动物后缀,悬停可查看完整会话名和工作目录。
|
|
260
296
|
连续 1 分钟没有收到新的 Agent 状态事件时,卡片和圆钮会一起自动隐藏;下一次收到事件时
|
|
261
297
|
会重新显示并重新计时。
|
|
262
298
|
|
|
@@ -410,15 +446,21 @@ defaults delete com.universewang.cc-pets CCPetsSpeechCooldown # 交
|
|
|
410
446
|
- macOS 13 或更高版本
|
|
411
447
|
- Node.js 18 或更高版本,仅供 npm 安装与升级使用;桌宠本身以及 `cc-pets` 命令、Hooks、
|
|
412
448
|
CC Bridge 都是原生程序,运行时不依赖 Node
|
|
413
|
-
-
|
|
449
|
+
- 已配置 Codex、Claude Code 或 Antigravity CLI(`agy`)中的至少一种
|
|
414
450
|
- zsh
|
|
415
451
|
- Xcode Command Line Tools,可通过 `xcode-select --install` 安装
|
|
416
452
|
|
|
417
453
|
## CC Bridge
|
|
418
454
|
|
|
419
|
-
[CC Bridge](./CC_BRIDGE.zh-CN.md) 是默认关闭的可选功能,让本机 Claude Code
|
|
455
|
+
[CC Bridge](./CC_BRIDGE.zh-CN.md) 是默认关闭的可选功能,让本机 Claude Code、Codex 和 Antigravity CLI 会话互发消息并预留文件。
|
|
456
|
+
原生 `agy` 在下一次模型调用时读取等待消息。[Antigravity App](./CC_BRIDGE.zh-CN.md#antigravity-app) 启用 Sidecar 后支持自动唤醒。
|
|
420
457
|
身份识别优先验证会话 ID;按 PID 回退时只接受唯一在线会话,共享宿主下身份不明确会拒绝操作。
|
|
421
458
|
Codex 消息使用接收方的 Home 投递。
|
|
459
|
+
多个 Codex 会话共用 app-server PID 时,Agent 在每次 MCP 调用中传入 Bridge hook 提供的当前 `session_id`。
|
|
460
|
+
更新后需重新连接 MCP,以加载新的工具定义。
|
|
461
|
+
|
|
462
|
+
中文显示会为自动生成的会话名附加动物别名,发送消息仍使用原始名称或 ref。
|
|
463
|
+
没有持久化转录的 Codex 临时任务不注册为收件人,但仍执行文件预留检查。
|
|
422
464
|
|
|
423
465
|
未确认的信箱消息可在异常退出后恢复。输出和确认之间崩溃时可能重复投递同一消息 ID;送达不代表已读或同意。
|
|
424
466
|
关闭自动唤醒后,已运行的 watcher 也会停止主动取信;关闭 Bridge 后 CLI 拒绝发送、改名和收件。
|
|
@@ -435,6 +477,8 @@ npm install -g cc-pets@latest --allow-scripts=cc-pets
|
|
|
435
477
|
codex
|
|
436
478
|
# 或
|
|
437
479
|
claude
|
|
480
|
+
# 或
|
|
481
|
+
agy
|
|
438
482
|
```
|
|
439
483
|
|
|
440
484
|
`--allow-scripts=cc-pets` 用于允许新版 npm 执行 CC Pets 的 `postinstall`,完成原生应用构建、
|
|
@@ -471,20 +515,22 @@ cc-pets install
|
|
|
471
515
|
codex
|
|
472
516
|
# 或
|
|
473
517
|
claude
|
|
518
|
+
# 或
|
|
519
|
+
agy
|
|
474
520
|
```
|
|
475
521
|
|
|
476
522
|
npm 12 会把本地目录安装识别为项目范围安装,不接受命令行传入的 `--allow-scripts`。
|
|
477
523
|
因此本地源码安装显式跳过生命周期脚本,再通过 `cc-pets install` 执行可重复的初始化流程。
|
|
478
524
|
|
|
479
|
-
两种方式都会安装 `cc-pets`、`codex-with-pet` 和 `
|
|
480
|
-
npm
|
|
481
|
-
`codex` 与 `
|
|
525
|
+
两种方式都会安装 `cc-pets`、`codex-with-pet`、`claude-with-pet` 和 `agy-with-pet`。
|
|
526
|
+
npm 的安装后脚本会自动构建原生应用、安装已发现账号的 Agent Hooks,并在 `~/.cc-pets/shims` 下生成指向包装脚本的
|
|
527
|
+
`codex`、`claude` 与 `agy` 软链,再向 `~/.zshrc` 追加带标记的配置,把该目录前置到 `PATH`。
|
|
482
528
|
用 shim 而不是 alias,是因为 alias 名区分大小写而 macOS 文件系统默认不区分:`Claude`、`CODEX` 这类写法
|
|
483
529
|
匹配不到 alias,会直接命中真二进制,桌宠不会被拉起。shim 让任意大小写写法都落到同一个文件上。
|
|
484
530
|
|
|
485
531
|
### 多账号
|
|
486
532
|
|
|
487
|
-
CC Pets
|
|
533
|
+
CC Pets 会自动发现并集成已安装 CLI 的默认 Home,包括 `~/.claude`、`~/.codex` 和 `~/.gemini`。`~/.claude-x`、
|
|
488
534
|
`~/.codex-work` 等自定义 Home 不会被自动扫描,必须从「主菜单 → 多账号」(位于“宠物”下方)手动添加。
|
|
489
535
|
默认使用文件夹名作为账号名称并保持原样,也可以在该页的“管理”菜单中重命名。每个 Provider
|
|
490
536
|
拥有独立的循环额度卡片,用量页也可以按账号筛选本机会话 Token 历史。
|
|
@@ -492,6 +538,13 @@ CC Pets 会自动发现并集成官方 `~/.claude` 和 `~/.codex` Home。`~/.cla
|
|
|
492
538
|
添加账号时会配置 Pet Hooks 和用量采集。若 CC Bridge 已开启,会同时配置它的 Hooks、
|
|
493
539
|
权限与 MCP;若尚未开启,之后启用 CC Bridge 时会自动为所有已登记账号补齐。
|
|
494
540
|
|
|
541
|
+
Antigravity Home 选择包含 `antigravity-cli/` 子目录的 Gemini 根目录。在多账号页添加自定义根目录后,
|
|
542
|
+
启动 `agy` 时可以指定对应目录。
|
|
543
|
+
|
|
544
|
+
```bash
|
|
545
|
+
CC_PETS_ANTIGRAVITY_HOME=/absolute/path/to/gemini-root agy
|
|
546
|
+
```
|
|
547
|
+
|
|
495
548
|
首次安装需要新开终端让 `PATH` 生效;以后升级只需执行 npm 命令。
|
|
496
549
|
同时会将标准 macOS 应用安装到 `~/Applications/CC Pets.app`,可从 Finder 或 Launchpad 启动,
|
|
497
550
|
不需要管理员权限。npm 升级时会同步更新该应用。
|
|
@@ -519,6 +572,8 @@ export CODEX_REAL_BIN=/absolute/path/to/codex
|
|
|
519
572
|
export CLAUDE_REAL_BIN=/absolute/path/to/claude
|
|
520
573
|
```
|
|
521
574
|
|
|
575
|
+
如果真实 Antigravity CLI 不在当前 `PATH`,设置 `AGY_REAL_BIN=/absolute/path/to/agy`。
|
|
576
|
+
|
|
522
577
|
## 命令说明
|
|
523
578
|
|
|
524
579
|
```bash
|
|
@@ -564,7 +619,7 @@ printf '%s' '{"schemaVersion":1,"provider":"MyAgent","state":"thinking"}' \
|
|
|
564
619
|
# 手动修复或重新初始化 Hooks、shell 集成,并让已运行桌宠加载当前版本
|
|
565
620
|
cc-pets install
|
|
566
621
|
|
|
567
|
-
# CC Bridge
|
|
622
|
+
# CC Bridge(实验性,默认关闭),详见 CC_BRIDGE.zh-CN.md
|
|
568
623
|
cc-pets bridge enable
|
|
569
624
|
cc-pets bridge status
|
|
570
625
|
cc-pets bridge disable
|
|
@@ -586,6 +641,9 @@ codex-with-pet
|
|
|
586
641
|
|
|
587
642
|
# 启动桌宠后进入 Claude Code CLI
|
|
588
643
|
claude-with-pet
|
|
644
|
+
|
|
645
|
+
# 启动桌宠后进入原生 Antigravity CLI
|
|
646
|
+
agy-with-pet
|
|
589
647
|
```
|
|
590
648
|
|
|
591
649
|
项目版本以 `package.json` 为唯一来源。发布新版本时执行 `npm version patch`、
|
|
@@ -615,6 +673,12 @@ Claude 用量来自官方 status line 输入中的 `rate_limits.five_hour` 与
|
|
|
615
673
|
`rate_limits.seven_day`。其中的 `used_percentage` 会换算为剩余百分比。该字段仅面向
|
|
616
674
|
Claude.ai Pro/Max 订阅账号,并在会话完成首次 API 响应后出现;字段尚不可用时显示 `--`。
|
|
617
675
|
|
|
676
|
+
Antigravity CLI 从 `~/.gemini/antigravity-cli/brain` 或已登记 CLI Home 的对应目录读取会话转录,
|
|
677
|
+
Antigravity App 从 `~/.gemini/antigravity/brain` 读取。两种来源的 Token 和请求数分别展示。
|
|
678
|
+
Antigravity 的展示模式位于「设置 → 悬停面板显示」,与 Codex 和 Claude 使用同一组设置。
|
|
679
|
+
订阅额度由 `agy -p /usage --output-format json` 读取,每个已登录账号只显示一份可用的五小时与周额度。
|
|
680
|
+
API key 模式展示本地用量。
|
|
681
|
+
|
|
618
682
|
Claude Code 本地 Token 来自 `~/.claude/projects` 下的会话转录:
|
|
619
683
|
|
|
620
684
|
- 每条 `type = assistant` 的记录带 `message.usage`,是**单次请求的增量**,与 Codex 的
|
|
@@ -643,9 +707,9 @@ Codex 侧同理:桌宠固定只统计 `~/.codex`,不读继承来的 `CODEX_H
|
|
|
643
707
|
本地 Token 是 CLI 会话事件的原始计数,不等同于订阅额度。官方额度可能受模型、缓存和
|
|
644
708
|
请求复杂度等因素影响,应始终以服务端返回的百分比为准。
|
|
645
709
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
自然日窗口(今日 = 本机零点至今,最近 7 天 = 含今天在内的 7
|
|
710
|
+
额度详情面板用青色标识 Codex、紫色标识 Claude、蓝色标识 Antigravity。标题行显示在线 Agent 数,下方分别展示
|
|
711
|
+
Codex、Claude、Antigravity CLI 和 Antigravity App 的「今日」与「最近 7 天」Token,并显示最近刷新时间。统计用的是与订阅无关的
|
|
712
|
+
自然日窗口(今日 = 本机零点至今,最近 7 天 = 含今天在内的 7 个自然日),因为各家的
|
|
649
713
|
`resets_at` 并不一致,按各自订阅窗口算出的数不在同一区间上,相加没有意义。每个 Agent 卡片按 5 小时和 7 天两列
|
|
650
714
|
展示官方剩余百分比(主值)、本机 Token 用量和重置时间,右侧是近 7 天额度趋势。右键菜单的
|
|
651
715
|
“用量展示模式”保留原有切换控件,按已登记账号分别设置,旧的平台设置作为未单独设置账号的默认值。
|
|
@@ -656,7 +720,7 @@ API 用量模式只替换对应
|
|
|
656
720
|
“调用次数”来自本机会话记录:Claude 按请求标识去重,Codex 按去重后的累计 Token 快照计数。
|
|
657
721
|
某个窗口
|
|
658
722
|
当前没有额度数据时该列标注"当前无活跃窗口"。卡片上的在线徽章表示该 Provider 是否还有
|
|
659
|
-
运行中的客户端(包装脚本写出的 pid
|
|
723
|
+
运行中的客户端(包装脚本写出的 pid 文件、当前 Codex 桌面应用实例中的持久化聊天,或该 Provider 最近 60 秒内仍在发事件),与是否
|
|
660
724
|
已采集到额度数据无关;客户端退出后显示"离线",从未采集到数据时显示"等待数据"。经
|
|
661
725
|
`codex-with-pet` / `claude-with-pet` 启动的会话退出后 3 秒内转为离线;直接运行 `codex` /
|
|
662
726
|
`claude` 时没有可靠的退出信号,最多需要 60 秒静默才会转为离线。服务端的 Unix 时间戳会使用 Mac 当前系统时区
|
|
@@ -783,9 +847,9 @@ PetDex 官方 CLI(`npx petdex install <slug>`)会把素材放在 `~/.petdex/
|
|
|
783
847
|
- Claude 额度只从 Claude Code 传给本机 status line 的 `rate_limits` 字段读取。
|
|
784
848
|
- 为区分 API 账号和订阅账号,CC Pets 会读取各已登记 Home 中的认证配置(Claude 的 `settings.json`;Codex 的 `auth.json` 和 `config.toml`),并可能在本机运行该 Home 的 `claude auth status` / `codex login status`。只在内存中保留识别出的模式,不保存密钥、邮箱或命令输出。
|
|
785
849
|
- 诊断页修复前,会把受影响的配置文件和脚本备份到 `~/Library/Application Support/CC Pets/diagnostic-backups/`(仅本人可读),备份只保存在本机。
|
|
786
|
-
- Agent Hooks
|
|
850
|
+
- Agent Hooks 向当前用户的临时目录写入脱敏状态事件和额度缓存;事件可包含工作目录、Home 和转录路径,用于会话标签与生命周期跟踪,不包含转录正文。
|
|
787
851
|
- 额度历史默认关闭;启用后只在本机保留最近 7 天的剩余比例快照。
|
|
788
|
-
-
|
|
852
|
+
- 状态卡显示会话标签、状态及脱敏工具类别,悬停提示可显示完整会话名和工作目录;Agent 通知显示 Provider 和脱敏状态,不显示会话正文。
|
|
789
853
|
- 项目不上传会话内容、额度、凭据或使用统计,也不包含遥测服务。
|
|
790
854
|
- 桌宠启动时及 CLI 再次唤起桌宠时会向 npm Registry 查询最新版本号(同一次运行内最多每 10 分钟一次);仅在有新版本时再读取该版本 tag 中已提交的 Release Note,依次尝试 raw.githubusercontent.com、jsDelivr,最后回退到 GitHub Release API。请求不携带任何账号或使用数据。
|
|
791
855
|
- 右键“退出桌宠”或执行 `cc-pets uninstall` 后,不会继续运行后台守护进程。
|
|
Binary file
|