cc-pets 2.0.3 → 2.1.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 +239 -0
- package/CC_BRIDGE.zh-CN.md +210 -0
- package/CHANGELOG.md +13 -0
- package/CHANGELOG.zh-CN.md +13 -0
- package/PROVIDER_PROTOCOL.md +6 -0
- package/PROVIDER_PROTOCOL.zh-CN.md +5 -0
- package/README.md +6 -0
- package/README.zh-CN.md +7 -0
- package/Sources/CCPets/CCPetsAppDelegate.h +13 -0
- package/Sources/CCPets/CCPetsAppDelegate.m +357 -7
- package/Sources/CCPets/CCPetsBridge.h +43 -0
- package/Sources/CCPets/CCPetsBridge.m +198 -0
- package/Sources/CCPets/PetView.m +84 -0
- package/bin/cc-pets +5 -0
- package/package.json +3 -1
- package/scripts/bridge/cli.mjs +229 -0
- package/scripts/bridge/core.mjs +227 -0
- package/scripts/bridge/hook.mjs +149 -0
- package/scripts/bridge/install.mjs +288 -0
- package/scripts/bridge/mcp-server.mjs +300 -0
- package/scripts/bridge/options.mjs +86 -0
- package/scripts/bridge/process.mjs +129 -0
- package/scripts/bridge/reservations.mjs +247 -0
- package/scripts/bridge/store.mjs +432 -0
- package/scripts/bridge/watch.mjs +69 -0
- package/scripts/install-shell-integration.sh +3 -0
- package/scripts/uninstall-integrations.mjs +10 -0
package/CC_BRIDGE.md
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
# CC Bridge (experimental, off by default)
|
|
2
|
+
|
|
3
|
+
English | [简体中文](./CC_BRIDGE.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
CC Bridge lets Claude Code and Codex terminal sessions running on the same Mac discover
|
|
6
|
+
each other, exchange messages, and wake each other up. It mirrors Claude Code's native
|
|
7
|
+
cross-session messaging (`ListAgents` / `SendMessage`) and extends it to
|
|
8
|
+
Claude ↔ Codex and Codex ↔ Codex.
|
|
9
|
+
|
|
10
|
+
It uses only documented extension points of both CLIs: hooks, MCP, and `codex queue`.
|
|
11
|
+
It does not use internal protocols, inject keystrokes into terminals, or edit transcripts.
|
|
12
|
+
|
|
13
|
+
## Enable and disable
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cc-pets bridge enable # Write hooks, register the MCP server, and turn CC Bridge on
|
|
17
|
+
cc-pets bridge status # Show the switch, options, online sessions, and recent messages
|
|
18
|
+
cc-pets bridge disable # Remove every CC Bridge integration and turn it off
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
You can also toggle everything from the pet's right-click menu under **CC Bridge**; see [Pet menu](#pet-menu).
|
|
22
|
+
|
|
23
|
+
After enabling:
|
|
24
|
+
|
|
25
|
+
- Running Claude Code sessions hot-reload hooks and **start receiving messages immediately**, but only
|
|
26
|
+
get the MCP tools after a restart. Until then they can reply from Bash with
|
|
27
|
+
`cc-pets bridge send <name> '<text>'` (delivered messages include this hint).
|
|
28
|
+
- Running Codex sessions need a **restart**. Then run `/hooks` to trust the cc-pets bridge hooks;
|
|
29
|
+
Codex skips untrusted hooks, so that session will not appear in the list.
|
|
30
|
+
- Codex asks for approval on every MCP tool call by default (calls fail outright when the approval
|
|
31
|
+
policy is `never`), and Claude Code asks according to your permission settings. Opt in as needed;
|
|
32
|
+
see [Options](#options).
|
|
33
|
+
|
|
34
|
+
`cc-pets uninstall` also removes CC Bridge integrations. Reinstalls and upgrades rewrite them
|
|
35
|
+
with the saved options when CC Bridge is enabled.
|
|
36
|
+
|
|
37
|
+
### Options
|
|
38
|
+
|
|
39
|
+
`enable` and `configure` take the same options, and **anything you leave out keeps its current value**.
|
|
40
|
+
`configure` only changes options without re-registering the MCP server, so it's faster:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
cc-pets bridge configure --approve=view,send # No approval prompts in Codex and Claude
|
|
44
|
+
cc-pets bridge configure --codex-approve=view # Codex only
|
|
45
|
+
cc-pets bridge configure --claude-allow= # Clear Claude's allow list
|
|
46
|
+
cc-pets bridge configure --wake=off # Turn off auto-wake
|
|
47
|
+
cc-pets bridge configure --edit-guard=off # Turn off the reservation edit guard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
| Option | Description |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `--approve` / `--codex-approve` / `--claude-allow` | Tools that skip approval. Use groups `view` (list sessions, list reservations, read inbox), `send`, `reserve` (reserve / release), `name`, or tool names. Codex gets a marked block at the end of `~/.codex/config.toml`; Claude gets entries in `~/.claude/settings.json` `permissions.allow` (only `mcp__cc-bridge__*` entries are touched). `disable` removes both |
|
|
53
|
+
| `--wake=on\|off` | Wake idle sessions automatically (default on). When off, messages wait in the inbox until the recipient's next prompt, which saves tokens |
|
|
54
|
+
| `--edit-guard=on\|off` | Pause the first edit to a file another session reserved (default on) |
|
|
55
|
+
|
|
56
|
+
Claude picks up changes immediately; Codex needs a session restart (and re-trusting in `/hooks` when hooks change).
|
|
57
|
+
|
|
58
|
+
## Usage
|
|
59
|
+
|
|
60
|
+
Ask in plain language in any session:
|
|
61
|
+
|
|
62
|
+
> List the other agent sessions on this Mac, then tell codex-my-app-1 that the endpoint is now POST /api/pets.
|
|
63
|
+
|
|
64
|
+
The agent uses these MCP tools:
|
|
65
|
+
|
|
66
|
+
| Tool | Description |
|
|
67
|
+
| --- | --- |
|
|
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. |
|
|
70
|
+
| `set_name` | Renames the current session. |
|
|
71
|
+
| `reserve_files` | Reserves files or directories you are about to edit (globs supported); returns conflicts when they overlap with other reservations. |
|
|
72
|
+
| `release_files` | Releases this session's reservations. |
|
|
73
|
+
| `list_reservations` | Lists reservations in the current repository, or who reserved a given file. |
|
|
74
|
+
| `check_inbox` | Reads the inbox manually. Messages are normally delivered automatically. |
|
|
75
|
+
|
|
76
|
+
### Session names
|
|
77
|
+
|
|
78
|
+
Default names look like `<claude|codex>-<project-directory>-<n>`, for example `claude-my-app-1`.
|
|
79
|
+
When several terminals share a directory, give them memorable names:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
CC_BRIDGE_NAME=frontend claude # Registers as frontend; becomes frontend-2 if taken
|
|
83
|
+
CC_BRIDGE_NAME=api codex
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
You can also ask the agent to rename the session (which calls `set_name`), or run
|
|
87
|
+
`cc-pets bridge name frontend` from a Claude shell. Names may contain lowercase letters, digits,
|
|
88
|
+
and `. _ -`, up to 40 characters.
|
|
89
|
+
|
|
90
|
+
`list_agents` and `cc-pets bridge status` show each session's terminal (such as `ttys003`), so you
|
|
91
|
+
can say "send it to the session in ttys003".
|
|
92
|
+
|
|
93
|
+
## How to talk to agents
|
|
94
|
+
|
|
95
|
+
Plain language works; you don't need to remember tool names. Tip: **mention "cc-bridge" or the
|
|
96
|
+
recipient's session name**, so the agent calls the tools directly instead of searching the project
|
|
97
|
+
for what "bridge" means. The examples below assume two sessions named `web` (Claude) and `api` (Codex).
|
|
98
|
+
|
|
99
|
+
**You can also just call it "pet"**, with the same effect:
|
|
100
|
+
|
|
101
|
+
> Use pet to tell web the endpoint is ready
|
|
102
|
+
> Have pet pass a note to api: don't touch backend/ yet
|
|
103
|
+
> Pet, who's online?
|
|
104
|
+
> Use pet to reserve src/api before you start
|
|
105
|
+
|
|
106
|
+
"Pet" is a domain concept in many projects (think `/api/pets` in the Petstore example), so pair it
|
|
107
|
+
with an action: "**use pet to tell**…", "**have pet pass a note to**…", "**pet, who's online**".
|
|
108
|
+
A request like "add a field to pet" is read as a code change and won't trigger CC Bridge. Restart
|
|
109
|
+
Claude / Codex sessions for wording changes to take effect (MCP instructions load at session start).
|
|
110
|
+
|
|
111
|
+
### Common requests
|
|
112
|
+
|
|
113
|
+
| You want to | Say something like |
|
|
114
|
+
| --- | --- |
|
|
115
|
+
| See who's online | Use cc-bridge to list the sessions that are online |
|
|
116
|
+
| 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 |
|
|
117
|
+
| Hand off a task | Ask web to write unit tests for src/api/login.ts and report back |
|
|
118
|
+
| Get an answer back | Ask api how far the database migration has gone, and have it reply through cc-bridge |
|
|
119
|
+
| Wait until it's done | Tell api to run the test suite, and notify you when it goes idle |
|
|
120
|
+
| Target by terminal | Send this to the Claude session in ttys003: … |
|
|
121
|
+
|
|
122
|
+
Replies arrive as new messages in your session. "Notify you when it goes idle" sends a one-shot
|
|
123
|
+
notice once the recipient finishes its turn (`notify_when_idle`), which is handy for "continue after
|
|
124
|
+
it's done".
|
|
125
|
+
|
|
126
|
+
### Several sessions in one repository
|
|
127
|
+
|
|
128
|
+
- Before starting: "Use cc-bridge to reserve src/api with the reason 'login refactor', then start;
|
|
129
|
+
release it when you're done."
|
|
130
|
+
- Check: "Who has reserved which files in this repository?"
|
|
131
|
+
- On conflict: the first edit another session makes to a reserved file is paused once, showing who
|
|
132
|
+
reserved it and why; it usually coordinates first. If you really want the edit, say "I know web is
|
|
133
|
+
working on it, go ahead and change src/api/user.ts." One retry goes through, and that reservation
|
|
134
|
+
won't pause it again.
|
|
135
|
+
|
|
136
|
+
### Typical workflows
|
|
137
|
+
|
|
138
|
+
**Split frontend and backend**
|
|
139
|
+
|
|
140
|
+
1. In `web`: "Reserve frontend/ and start on the login page."
|
|
141
|
+
2. In `api`: "Reserve backend/, implement the login endpoint, and send the API shape to web through cc-bridge when done."
|
|
142
|
+
3. `api` sends the message, `web` wakes up and wires up the frontend.
|
|
143
|
+
|
|
144
|
+
**Ask another session to review**
|
|
145
|
+
|
|
146
|
+
> Send the list of files you just changed and the key points to api, ask it for a review, and have it reply with any issues.
|
|
147
|
+
|
|
148
|
+
### Tips
|
|
149
|
+
|
|
150
|
+
- Messages are **teammate requests**: the recipient acts within **its own permissions**, and actions
|
|
151
|
+
that need approval there still prompt.
|
|
152
|
+
- Codex asks for approval on every cc-bridge tool call by default; read-only tools are safe to allow:
|
|
153
|
+
`cc-pets bridge enable --codex-approve=list_agents,list_reservations,check_inbox`.
|
|
154
|
+
- Claude sessions started before CC Bridge was enabled receive messages but don't have the tools;
|
|
155
|
+
they can only reply with `cc-pets bridge send` from a shell. Restarting is simplest.
|
|
156
|
+
- Watch the pet: a blue number on the status icon means sessions are talking; open it to see who
|
|
157
|
+
messaged whom and click to jump to that terminal (see below).
|
|
158
|
+
|
|
159
|
+
## File reservations
|
|
160
|
+
|
|
161
|
+
When several agents work in the same repository, the biggest risk is two sessions editing the same
|
|
162
|
+
file. File reservations let an agent announce "I'm about to change `src/api/**`" before a larger edit:
|
|
163
|
+
|
|
164
|
+
- A reservation that overlaps someone else's returns the conflicts (holder, reason, time left), so the
|
|
165
|
+
agent can coordinate with `send_message`.
|
|
166
|
+
- The **first time** another session edits a reserved file (Claude's Edit / Write / MultiEdit /
|
|
167
|
+
NotebookEdit, Codex's apply_patch), that edit is **paused once** and the agent sees who reserved it
|
|
168
|
+
and why. If the user explicitly asked for the change, retrying lets it through and that reservation
|
|
169
|
+
never pauses it again; otherwise the agent should coordinate or work elsewhere.
|
|
170
|
+
- Reservations are **advisory**: files are not locked and edits never get stuck; the pause only
|
|
171
|
+
guarantees the agent notices.
|
|
172
|
+
- They expire after 30 minutes by default (up to 8 hours), renew when reserved again, and are released
|
|
173
|
+
when the session ends.
|
|
174
|
+
- They are scoped to the repository root, so different repositories and worktrees never collide. Only
|
|
175
|
+
path patterns and reasons are stored, never file contents.
|
|
176
|
+
|
|
177
|
+
Just ask: "Reserve src/api before you start the refactor, and release it when you're done."
|
|
178
|
+
|
|
179
|
+
## Delivery
|
|
180
|
+
|
|
181
|
+
| Recipient | Idle | Busy | Exited |
|
|
182
|
+
| --- | --- | --- | --- |
|
|
183
|
+
| Codex | Woken immediately through `codex queue` | Queued after the current turn | Not delivered; receipt is undeliverable |
|
|
184
|
+
| Claude Code | Woken by a background `asyncRewake` watcher | Injected into the current turn | Not delivered; receipt is undeliverable |
|
|
185
|
+
|
|
186
|
+
The Claude Code watcher arms at session start and at the end of every turn, and waits up to about
|
|
187
|
+
55 minutes before exiting. If a Claude session stays idle through that gap, messages stay in its
|
|
188
|
+
inbox and are included with the user's next prompt; messages that arrive during that turn are
|
|
189
|
+
delivered when it ends.
|
|
190
|
+
|
|
191
|
+
Senders get receipts such as "queued", "in inbox", or "undeliverable". Delivery does not mean
|
|
192
|
+
the recipient has read or agreed to anything.
|
|
193
|
+
|
|
194
|
+
## In the pet
|
|
195
|
+
|
|
196
|
+
With CC Bridge enabled, the round icon on the pet's status card gets a message badge in its
|
|
197
|
+
bottom-right corner (the red top-right badge still counts pending approvals):
|
|
198
|
+
|
|
199
|
+
- **Blue**: cross-session messages delivered since the pet started.
|
|
200
|
+
- **Orange**: messages waiting in some session's inbox (usually a long-idle Claude session); say
|
|
201
|
+
anything in that terminal to deliver them.
|
|
202
|
+
|
|
203
|
+
Click the icon to open the session menu. The "CC Bridge messages" section at the top lists the last
|
|
204
|
+
30 minutes of traffic (such as `api → web · 22:43`) and inbox reminders; click one to jump to the
|
|
205
|
+
**recipient's terminal**. The session list below shows each session's CC Bridge name. Opening the
|
|
206
|
+
menu marks messages as seen. The menu and badge show names and times only, never message bodies.
|
|
207
|
+
|
|
208
|
+
## Pet menu
|
|
209
|
+
|
|
210
|
+
Right-click the pet → **CC Bridge**:
|
|
211
|
+
|
|
212
|
+
| Switch | Effect |
|
|
213
|
+
| --- | --- |
|
|
214
|
+
| 启用 (Enable) | Same as `cc-pets bridge enable / disable`; takes a few seconds |
|
|
215
|
+
| 免审批 (Skip approval): 查看类 view / 发消息 send / 文件预留 reserve / 改会话名 rename | Each group applies to both Codex approval and Claude permissions. With "send" on, agents can message other sessions without asking |
|
|
216
|
+
| 自动唤醒 (Auto-wake) | Same as `--wake` |
|
|
217
|
+
| 编辑拦截 (Edit guard) | Same as `--edit-guard` |
|
|
218
|
+
| 消息角标 (Message badge) | Pet only: show the message badge on the status icon |
|
|
219
|
+
| 新消息通知 (New-message notifications) | Pet only: a system notification when sessions message each other (sender and recipient only, never the body); asks for notification permission the first time |
|
|
220
|
+
|
|
221
|
+
The pet's UI is currently in Simplified Chinese. The bottom of the menu shows "N 会话 · M 预留"
|
|
222
|
+
(online sessions and active reservations), and each switch has a hover tooltip. Except for the badge and
|
|
223
|
+
notification switches, everything is dimmed while CC Bridge is off. The menu finds the command-line
|
|
224
|
+
tool through `~/.cc-pets/bridge-cli.json`, written on every `cc-pets install`; if it's missing, you'll be asked to reinstall.
|
|
225
|
+
|
|
226
|
+
## Security and privacy
|
|
227
|
+
|
|
228
|
+
- Delivered messages carry a source header. The agent treats them as a **teammate's request** and
|
|
229
|
+
acts within **its own session's permission settings**. A message cannot escalate permissions:
|
|
230
|
+
it must not be used to change permissions or configuration or to approve a pending prompt, and
|
|
231
|
+
when a peer asks for an action that was denied on its side, the agent should refuse and tell the user.
|
|
232
|
+
- Message bodies are stored in the current user's temporary directory
|
|
233
|
+
(`cc-bridge-<uid>/` under `getconf DARWIN_USER_TEMP_DIR`) with `0700` directories and `0600`
|
|
234
|
+
files; undelivered messages expire after 24 hours. This is an explicit exception to the
|
|
235
|
+
[Provider protocol](./PROVIDER_PROTOCOL.md)'s no-content rule, which is why CC Bridge is off by default.
|
|
236
|
+
- A message is limited to 16 KB. A pair of sessions exchanging more than 20 messages within
|
|
237
|
+
10 minutes is paused to stop two agents from auto-replying to each other in a loop.
|
|
238
|
+
- Pet status cards and notifications never show message bodies.
|
|
239
|
+
- No background daemon: only hooks, the MCP server, and the watcher inside Claude sessions, all of which exit with the session.
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# CC Bridge(实验性,默认关闭)
|
|
2
|
+
|
|
3
|
+
[English](./CC_BRIDGE.md) | 简体中文
|
|
4
|
+
|
|
5
|
+
CC Bridge 让本机同时运行的 Claude Code 与 Codex 终端会话互相发现、发消息、唤醒对方,
|
|
6
|
+
体验对齐 Claude Code 原生的跨会话消息(`ListAgents` / `SendMessage`),并且支持
|
|
7
|
+
Claude ↔ Codex、Codex ↔ Codex。
|
|
8
|
+
|
|
9
|
+
它只使用两边官方公开的扩展点:hooks、MCP、`codex queue`。不接入任何内部协议,
|
|
10
|
+
不向终端注入按键,不修改会话记录。
|
|
11
|
+
|
|
12
|
+
## 开启与关闭
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
cc-pets bridge enable # 写入 hooks、注册 MCP,并打开开关
|
|
16
|
+
cc-pets bridge status # 查看开关、选项、在线会话与最近消息
|
|
17
|
+
cc-pets bridge disable # 移除全部 CC Bridge 集成并关闭
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
也可以在桌宠右键菜单的 **CC Bridge** 里直接开关,见下文[桌宠菜单](#桌宠菜单)。
|
|
21
|
+
|
|
22
|
+
开启后:
|
|
23
|
+
|
|
24
|
+
- 已经在运行的 Claude Code 会话会热加载 hooks,**立即开始接收消息**,但 MCP 工具要重启后才有;
|
|
25
|
+
在此之前可以在 Bash 里用 `cc-pets bridge send <名字> '<内容>'` 回复(收到的消息里会附带这条提示)。
|
|
26
|
+
- 已经在运行的 Codex 会话需要**重启**。启动后执行 `/hooks`,信任 cc-pets bridge 的 hooks;
|
|
27
|
+
未信任的 hooks 会被 Codex 跳过,对应会话不会出现在列表里。
|
|
28
|
+
- Codex 默认每次调用 MCP 工具都要审批(审批策略为 `never` 时调用会直接失败);Claude Code 首次调用时也会按你的
|
|
29
|
+
权限设置询问。可以按需放开,见下方[选项](#选项)。
|
|
30
|
+
|
|
31
|
+
`cc-pets uninstall` 也会一并移除 CC Bridge 集成;重装或升级时,已开启的 CC Bridge 会按原选项自动重写集成。
|
|
32
|
+
|
|
33
|
+
### 选项
|
|
34
|
+
|
|
35
|
+
`enable` 与 `configure` 接受同一组选项,**没给的保持原值**;`configure` 只改选项、不重新注册 MCP,更快:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
cc-pets bridge configure --approve=view,send # Codex 与 Claude 同时免审批
|
|
39
|
+
cc-pets bridge configure --codex-approve=view # 只设 Codex
|
|
40
|
+
cc-pets bridge configure --claude-allow= # 清空 Claude 免确认
|
|
41
|
+
cc-pets bridge configure --wake=off # 关闭自动唤醒
|
|
42
|
+
cc-pets bridge configure --edit-guard=off # 关闭编辑前预留拦截
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| 选项 | 说明 |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `--approve` / `--codex-approve` / `--claude-allow` | 免审批的工具。可写分组 `view`(列会话、查预留、读信箱)、`send`(发消息)、`reserve`(预留 / 释放)、`name`(改名),或具体工具名。Codex 写入 `~/.codex/config.toml` 末尾的带标记块,Claude 写入 `~/.claude/settings.json` 的 `permissions.allow`(只增删 `mcp__cc-bridge__*` 条目);`disable` 时一并移除 |
|
|
48
|
+
| `--wake=on\|off` | 自动唤醒空闲会话,默认开。关闭后消息只进信箱,等对方下次收到你的输入时带入,可省 token |
|
|
49
|
+
| `--edit-guard=on\|off` | 编辑他人预留的文件时暂停一次,默认开 |
|
|
50
|
+
|
|
51
|
+
Claude 侧的改动会被热加载;Codex 侧(审批、hooks)需要重启 Codex 会话,hooks 变化后还要在 `/hooks` 中重新信任。
|
|
52
|
+
|
|
53
|
+
## 使用
|
|
54
|
+
|
|
55
|
+
在任意一个会话里直接用自然语言:
|
|
56
|
+
|
|
57
|
+
> 列出本机其他 Agent 会话,然后给 codex-my-app-1 发消息:接口改成了 POST /api/pets,你那边同步一下。
|
|
58
|
+
|
|
59
|
+
Agent 会调用这些 MCP 工具:
|
|
60
|
+
|
|
61
|
+
| 工具 | 说明 |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `list_agents` | 列出在线会话:名字 [ref]、CLI、忙闲、所在终端(tty)、启动时间、目录。名字就是地址;只有重名时才需要写成 `名字 [ref]`。 |
|
|
64
|
+
| `send_message` | 发消息;`notify_when_idle: true` 时,对方下次完成回合后你会收到一条一次性空闲通知。 |
|
|
65
|
+
| `set_name` | 修改当前会话的名字。 |
|
|
66
|
+
| `reserve_files` | 预留即将修改的文件或目录(支持 glob),与他人预留重叠时返回冲突列表。 |
|
|
67
|
+
| `release_files` | 释放本会话的预留。 |
|
|
68
|
+
| `list_reservations` | 查看当前仓库的所有预留,或某个文件被谁预留。 |
|
|
69
|
+
| `check_inbox` | 手动读取信箱。正常情况下消息会自动送达,一般不需要调用。 |
|
|
70
|
+
|
|
71
|
+
### 会话名
|
|
72
|
+
|
|
73
|
+
默认名字是 `<claude|codex>-<项目目录名>-<序号>`,例如 `claude-my-app-1`。同一目录开多个终端时,
|
|
74
|
+
可以给它们起好记的名字:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
CC_BRIDGE_NAME=frontend claude # 以 frontend 注册;被占用时自动变成 frontend-2
|
|
78
|
+
CC_BRIDGE_NAME=api codex
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
也可以在会话里让 Agent 改名("把本会话在 cc-bridge 里的名字改成 frontend",即调用 `set_name`),
|
|
82
|
+
或在 Claude 的 shell 里执行 `cc-pets bridge name frontend`。名字只能包含小写字母、数字和 `. _ -`,最长 40 个字符。
|
|
83
|
+
|
|
84
|
+
`list_agents` 与 `cc-pets bridge status` 会显示每个会话所在的终端(如 `ttys003`),
|
|
85
|
+
可以直接说"发给 ttys003 那个会话"。
|
|
86
|
+
|
|
87
|
+
## 怎么和 Agent 说
|
|
88
|
+
|
|
89
|
+
用自然语言即可,不需要记工具名。小技巧:**说话时带上"cc-bridge"或对方的会话名**,Agent 会直接调用工具,
|
|
90
|
+
而不是先去项目文件里搜"bridge"是什么。下面的例子假设两个会话分别以 `web`(Claude)和 `api`(Codex)命名。
|
|
91
|
+
|
|
92
|
+
**也可以直接叫它"pet"或"桌宠"**,效果相同:
|
|
93
|
+
|
|
94
|
+
> 用 pet 发给 web:接口改好了
|
|
95
|
+
> 让桌宠转告 api:先别动 backend/
|
|
96
|
+
> pet 看看谁在线
|
|
97
|
+
> 用 pet 预留 src/api 再开始改
|
|
98
|
+
|
|
99
|
+
"pet"在很多项目里本身就是业务概念(比如 Petstore 示例里的 `/api/pets`),所以请带上动作来说——
|
|
100
|
+
"**用 pet 发给**……""**让桌宠转告**……""**pet 看看谁在线**"。像"给 pet 加个字段"这种说法,Agent 会理解成改业务代码,
|
|
101
|
+
不会去调用 CC Bridge。说法改动需要重启 Claude / Codex 会话后才生效(MCP 说明在会话启动时加载)。
|
|
102
|
+
|
|
103
|
+
### 常用说法
|
|
104
|
+
|
|
105
|
+
| 想做的事 | 可以这样说 |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| 看谁在线 | 用 cc-bridge 看看现在有哪些会话在线 |
|
|
108
|
+
| 通知对方 | 用 cc-bridge 告诉 api:登录接口改成了 POST /api/login,返回字段加了 token,你那边同步改一下前端调用 |
|
|
109
|
+
| 分派任务 | 让 web 帮忙写 src/api/login.ts 的单元测试,写完告诉我结果 |
|
|
110
|
+
| 要对方回复 | 问一下 api 数据库迁移做到哪一步了,让它用 cc-bridge 回复你 |
|
|
111
|
+
| 等对方做完 | 给 api 发消息让它跑一遍测试,并在它空闲时通知你 |
|
|
112
|
+
| 按终端指定 | 发给 ttys003 那个 Claude 会话:…… |
|
|
113
|
+
|
|
114
|
+
对方的回复会作为一条新消息出现在当前会话里。"在它空闲时通知你"会让对方这一轮做完后,
|
|
115
|
+
当前会话收到一条一次性的空闲通知(`notify_when_idle`),适合"等它做完我再继续"。
|
|
116
|
+
|
|
117
|
+
### 多个会话改同一个仓库
|
|
118
|
+
|
|
119
|
+
- 开工前预留:"先用 cc-bridge 预留 src/api 目录,原因写'重构登录',再开始改;改完释放预留。"
|
|
120
|
+
- 查看预留:"看看这个仓库现在谁预留了哪些文件。"
|
|
121
|
+
- 遇到冲突:另一个会话第一次去改被预留的文件时会被暂停一次,并看到是谁、为什么预留,通常会先发消息协调。
|
|
122
|
+
如果确实要它改,直接说:"我知道 web 在改,你照样改 src/api/user.ts。"它重试一次即可,之后不再被这处预留拦住。
|
|
123
|
+
|
|
124
|
+
### 典型协作流程
|
|
125
|
+
|
|
126
|
+
**前后端分工**
|
|
127
|
+
|
|
128
|
+
1. 在 `web` 里:"预留 frontend/ 目录,开始做登录页面。"
|
|
129
|
+
2. 在 `api` 里:"预留 backend/ 目录,实现登录接口,做完用 cc-bridge 把接口格式发给 web。"
|
|
130
|
+
3. `api` 做完发出消息,`web` 被唤醒,按接口格式完成对接。
|
|
131
|
+
|
|
132
|
+
**写完请另一个会话审查**
|
|
133
|
+
|
|
134
|
+
> 把刚才改动的文件列表和改动要点发给 api,让它帮忙 review,有问题直接回复你。
|
|
135
|
+
|
|
136
|
+
### 小贴士
|
|
137
|
+
|
|
138
|
+
- 消息是**队友的请求**,对方在**自己的权限范围内**处理:它那边需要审批的操作照样会弹审批。
|
|
139
|
+
- Codex 每次调用 cc-bridge 工具默认都要审批;只读类工具可以放开:
|
|
140
|
+
`cc-pets bridge enable --codex-approve=list_agents,list_reservations,check_inbox`。
|
|
141
|
+
- 开启 CC Bridge 之前就在运行的 Claude 会话能收消息,但没有这些工具,只能在 shell 里用 `cc-pets bridge send` 回复;重启一下最省事。
|
|
142
|
+
- 留意桌宠:状态图标右下角出现蓝色数字,说明会话之间有往来;点开能看到谁发给了谁,点一下即跳到对应终端(见下文)。
|
|
143
|
+
|
|
144
|
+
## 文件预留
|
|
145
|
+
|
|
146
|
+
多个 Agent 在同一个仓库里工作时,最怕两个会话同时改同一个文件。文件预留让 Agent 在开始较大的修改前
|
|
147
|
+
先声明"我要改 `src/api/**`":
|
|
148
|
+
|
|
149
|
+
- 其他会话预留时如果与之重叠,会收到冲突列表(持有者、原因、剩余时间),可以直接 `send_message` 协调;
|
|
150
|
+
- 其他会话**第一次编辑**被预留的文件时(Claude 的 Edit / Write / MultiEdit / NotebookEdit,Codex 的 apply_patch),
|
|
151
|
+
这次编辑会被**暂停一次**,Agent 会看到是谁、为什么预留。如果修改是用户明确要求的,重试即可放行,
|
|
152
|
+
之后这处预留不再拦它;否则 Agent 应先协调或改做其他部分。
|
|
153
|
+
- 预留是**建议性**的:不锁文件,不会把编辑卡死,只保证 Agent 一定会注意到。
|
|
154
|
+
- 默认 30 分钟过期(最长 8 小时),重复预留即续期;会话结束时自动释放。
|
|
155
|
+
- 按仓库根目录隔离:不同仓库、同一仓库的不同 worktree 互不影响。只记录路径模式和原因,不记录文件内容。
|
|
156
|
+
|
|
157
|
+
可以直接对 Agent 说:"先预留 src/api 目录再开始重构,改完释放。"
|
|
158
|
+
|
|
159
|
+
## 送达方式
|
|
160
|
+
|
|
161
|
+
| 目标 | 对方空闲 | 对方忙碌 | 对方已退出 |
|
|
162
|
+
| --- | --- | --- | --- |
|
|
163
|
+
| Codex | 通过 `codex queue` 立即唤醒 | 排在当前回合之后处理 | 不投递,回执为 undeliverable |
|
|
164
|
+
| Claude Code | 后台 watcher 通过 `asyncRewake` 唤醒 | 注入当前回合 | 不投递,回执为 undeliverable |
|
|
165
|
+
|
|
166
|
+
Claude Code 的 watcher 在会话启动和每轮结束时挂上,每次最多等待约 55 分钟后自动退出。
|
|
167
|
+
如果 Claude 会话在这段空窗期里一直空闲,消息会留在信箱,等用户下次输入时一并带入;
|
|
168
|
+
那一轮进行中新到的消息,在该轮结束时投递。
|
|
169
|
+
|
|
170
|
+
发送方只会收到"已送达队列 / 已放入信箱 / 无法投递"这类回执。送达不代表对方已读,也不代表对方同意。
|
|
171
|
+
|
|
172
|
+
## 桌宠里的显示
|
|
173
|
+
|
|
174
|
+
开启 CC Bridge 后,桌宠状态卡的圆形图标右下角会多一个消息角标(右上角的红色角标仍是待审批):
|
|
175
|
+
|
|
176
|
+
- **蓝色数字**:桌宠运行期间新送达的跨会话消息条数;
|
|
177
|
+
- **橙色数字**:有消息积压在某个会话的信箱里(通常是长时间空闲的 Claude 会话),需要你去那个终端说句话才会送达。
|
|
178
|
+
|
|
179
|
+
点击图标打开会话菜单,顶部的「CC Bridge 消息」列出最近 30 分钟的往来(如 `api → web · 22:43`)和积压提醒,
|
|
180
|
+
点击任一条即跳到**收件会话所在的终端**;下方的会话列表会带上各会话在 CC Bridge 中的名字。打开菜单即视为已读。
|
|
181
|
+
菜单与角标只显示会话名和时间,不显示消息正文。
|
|
182
|
+
|
|
183
|
+
## 桌宠菜单
|
|
184
|
+
|
|
185
|
+
桌宠右键菜单 → **CC Bridge**:
|
|
186
|
+
|
|
187
|
+
| 开关 | 作用 |
|
|
188
|
+
| --- | --- |
|
|
189
|
+
| 启用 | 等同 `cc-pets bridge enable / disable`,执行需要几秒 |
|
|
190
|
+
| 免审批:查看类 / 发消息 / 文件预留 / 改会话名 | 每组同时作用于 Codex 免审批与 Claude 免确认。"发消息"开启后,Agent 可以不经确认给其他会话发消息 |
|
|
191
|
+
| 自动唤醒 | 自动唤醒空闲会话,同 `--wake` |
|
|
192
|
+
| 编辑拦截 | 编辑前预留拦截,同 `--edit-guard` |
|
|
193
|
+
| 消息角标 | 只影响桌宠:是否显示状态图标右下角的消息角标 |
|
|
194
|
+
| 新消息通知 | 只影响桌宠:会话之间有消息送达时发系统通知(只含谁发给谁,不含正文),首次开启时申请通知权限 |
|
|
195
|
+
|
|
196
|
+
菜单底部显示"N 会话 · M 预留"(在线会话数与有效预留数),各开关悬停可看说明。除角标和通知外,其余开关在 CC Bridge 未开启时置灰。
|
|
197
|
+
菜单开关通过 `~/.cc-pets/bridge-cli.json` 找到命令行程序(每次 `cc-pets install` 时写入);找不到时会提示重新安装。
|
|
198
|
+
|
|
199
|
+
## 安全与隐私
|
|
200
|
+
|
|
201
|
+
- 收到的消息会带上来源标头,Agent 会把它当作**队友的请求**,在**本会话自身的权限设置内**处理。
|
|
202
|
+
这条消息不能提升权限:不能用来修改权限或配置,不能当作对待确认操作的批准;如果对方说某个操作
|
|
203
|
+
在它那边被拒绝、请你代为执行,Agent 应拒绝并告知用户。
|
|
204
|
+
- 消息正文保存在当前用户的临时目录(`getconf DARWIN_USER_TEMP_DIR` 下的 `cc-bridge-<uid>/`),
|
|
205
|
+
目录权限为 `0700`、文件权限为 `0600`,未投递的消息 24 小时后过期。
|
|
206
|
+
这是对 [Provider 协议](./PROVIDER_PROTOCOL.zh-CN.md)"不接收正文"原则的一个显式例外,
|
|
207
|
+
所以默认关闭,需要你主动开启。
|
|
208
|
+
- 单条消息最多 16KB。同一对会话 10 分钟内往来超过 20 条会被暂停,防止两个 Agent 互相自动回复形成循环。
|
|
209
|
+
- 桌宠的状态卡片与系统通知不会显示消息正文。
|
|
210
|
+
- 不引入常驻守护进程:只有 hooks、MCP server,以及 Claude 会话内的 watcher,都随会话结束而退出。
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,19 @@ English | [简体中文](./CHANGELOG.zh-CN.md)
|
|
|
5
5
|
This project follows Semantic Versioning. `package.json` is the single source of
|
|
6
6
|
truth for the version.
|
|
7
7
|
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### CC Bridge (experimental, off by default)
|
|
11
|
+
|
|
12
|
+
- Added `cc-pets bridge enable|disable|status`, which lets Claude Code and Codex terminal sessions on the same Mac discover each other, exchange messages, and wake each other, including Claude ↔ Codex and Codex ↔ Codex. See [CC_BRIDGE.md](./CC_BRIDGE.md).
|
|
13
|
+
- Uses documented extension points only: an MCP server (`list_agents` / `send_message` / `check_inbox`) for sending, `codex queue` for delivery to Codex, and an `asyncRewake` hook for delivery to Claude Code.
|
|
14
|
+
- Checks that the recipient is online before delivery so Codex never runs stale messages on resume; 16 KB message limit, 24-hour expiry, and a 20-messages-per-10-minutes pair limit to break auto-reply loops.
|
|
15
|
+
- `cc-pets uninstall` removes CC Bridge integrations; reinstalls and upgrades refresh them with the saved options.
|
|
16
|
+
- File reservations: `reserve_files` / `release_files` / `list_reservations`, where the first edit to a file someone else reserved is paused once by a PreToolUse hook with the reason, and a retry goes through; reservations expire and are released when the session ends.
|
|
17
|
+
- Pet integration: a message badge on the status icon (blue for new deliveries, orange for inbox backlog), recent cross-session messages in the session menu, and click-to-jump to the recipient's terminal; names and times only, never bodies.
|
|
18
|
+
- Options and pet switches: `cc-pets bridge configure` and `enable` accept `--approve` / `--codex-approve` / `--claude-allow` (skip approval in Codex and Claude by tool group), `--wake`, and `--edit-guard`, keeping anything not given; the pet's right-click menu gains a CC Bridge section (enable, four approval groups, auto-wake, edit guard, message badge, new-message notifications).
|
|
19
|
+
- Custom session names via `CC_BRIDGE_NAME` at launch, or `set_name` / `cc-pets bridge name` in a session; `list_agents` shows each session's terminal (tty).
|
|
20
|
+
|
|
8
21
|
## [2.0.3] - 2026-09-17
|
|
9
22
|
|
|
10
23
|
Terminal jump-back and session-liveness fixes for agents started outside the wrapper scripts.
|
package/CHANGELOG.zh-CN.md
CHANGED
|
@@ -4,6 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
本项目遵循语义化版本号。版本号以 `package.json` 为唯一来源。
|
|
6
6
|
|
|
7
|
+
## [未发布]
|
|
8
|
+
|
|
9
|
+
### CC Bridge(实验性,默认关闭)
|
|
10
|
+
|
|
11
|
+
- 新增 `cc-pets bridge enable|disable|status`:让本机的 Claude Code 与 Codex 终端会话互相发现、发消息、唤醒对方,支持 Claude ↔ Codex、Codex ↔ Codex,详见 [CC_BRIDGE.zh-CN.md](./CC_BRIDGE.zh-CN.md)。
|
|
12
|
+
- 只使用官方扩展点:MCP server(`list_agents` / `send_message` / `check_inbox`)负责发送;投递到 Codex 用 `codex queue`,投递到 Claude Code 用 `asyncRewake` hook。
|
|
13
|
+
- 投递前确认目标在线,避免 Codex 在 resume 时执行过期消息;单条 16KB 上限、24 小时过期、同一对会话 10 分钟 20 条的防循环限流。
|
|
14
|
+
- `cc-pets uninstall` 一并移除 CC Bridge 集成;重装与升级时按原选项自动刷新。
|
|
15
|
+
- 文件预留:`reserve_files` / `release_files` / `list_reservations`,第一次编辑他人预留的文件时由 PreToolUse hook 暂停一次并说明原因,重试即放行,过期与会话结束自动释放。
|
|
16
|
+
- 桌宠显示:状态图标右下角的消息角标(蓝色为新送达,橙色为信箱积压),会话菜单列出最近的跨会话消息,点击跳到收件会话的终端;只显示会话名与时间,不显示正文。
|
|
17
|
+
- 选项与菜单开关:`cc-pets bridge configure` 与 `enable` 支持 `--approve` / `--codex-approve` / `--claude-allow`(按分组放开 Codex 免审批与 Claude 免确认)、`--wake`、`--edit-guard`,未给出的选项保持原值;桌宠右键菜单新增 CC Bridge 开关组(启用、免审批四组、自动唤醒、编辑拦截、消息角标、新消息系统通知)。
|
|
18
|
+
- 会话名可自定义:启动时用 `CC_BRIDGE_NAME`,或会话内调用 `set_name` / `cc-pets bridge name`;`list_agents` 显示会话所在终端(tty)。
|
|
19
|
+
|
|
7
20
|
## [2.0.3] - 2026-09-17
|
|
8
21
|
|
|
9
22
|
修复未经包装脚本启动的 Agent 的终端回跳与会话存活判定。
|
package/PROVIDER_PROTOCOL.md
CHANGED
|
@@ -63,3 +63,9 @@ change the managed lifecycle of the Codex and Claude integrations.
|
|
|
63
63
|
|
|
64
64
|
An incompatible schema version or invalid field returns exit code `2`. A write
|
|
65
65
|
failure returns a non-zero exit code.
|
|
66
|
+
|
|
67
|
+
## Relationship to CC Bridge
|
|
68
|
+
|
|
69
|
+
This protocol carries state only, never content. To pass message content between sessions,
|
|
70
|
+
use [CC Bridge](./CC_BRIDGE.md), which is off by default and must be enabled explicitly. It does
|
|
71
|
+
not go through this protocol and does not change its field constraints.
|
package/README.md
CHANGED
|
@@ -132,6 +132,9 @@ cc-pets pet list # List installed assets.
|
|
|
132
132
|
cc-pets pet remove boba # Remove an installed asset.
|
|
133
133
|
|
|
134
134
|
cc-pets install # Repair or reinitialize integrations.
|
|
135
|
+
cc-pets bridge enable # CC Bridge (experimental, off by default); see CC_BRIDGE.md.
|
|
136
|
+
cc-pets bridge status # Show CC Bridge state and online sessions.
|
|
137
|
+
cc-pets bridge disable # Remove CC Bridge integrations.
|
|
135
138
|
cc-pets uninstall # Remove integrations and restore the status line.
|
|
136
139
|
cc-pets uninstall --purge # Also remove the app and all local data after confirmation.
|
|
137
140
|
cc-pets uninstall-app # Remove only ~/Applications/CC Pets.app.
|
|
@@ -304,6 +307,9 @@ external assets.
|
|
|
304
307
|
- Status cards and notifications show only provider, state, and redacted tool category.
|
|
305
308
|
- CC Pets contains no telemetry and uploads no conversations, quotas, credentials, or usage statistics.
|
|
306
309
|
- Exiting the pet or running `cc-pets uninstall` leaves no background daemon running.
|
|
310
|
+
- [CC Bridge](./CC_BRIDGE.md) is off by default. When enabled, messages between sessions are stored
|
|
311
|
+
in the current user's temporary directory (owner-only, 24-hour expiry); it is the only feature
|
|
312
|
+
that stores message content.
|
|
307
313
|
|
|
308
314
|
## Uninstall
|
|
309
315
|
|
package/README.zh-CN.md
CHANGED
|
@@ -390,6 +390,11 @@ printf '%s' '{"schemaVersion":1,"provider":"MyAgent","state":"thinking"}' \
|
|
|
390
390
|
# 手动修复或重新初始化 Hooks、shell 集成,并让已运行桌宠加载当前版本
|
|
391
391
|
cc-pets install
|
|
392
392
|
|
|
393
|
+
# CC Bridge(实验性,默认关闭):让本机 Claude Code / Codex 会话互发消息,详见 CC_BRIDGE.zh-CN.md
|
|
394
|
+
cc-pets bridge enable
|
|
395
|
+
cc-pets bridge status
|
|
396
|
+
cc-pets bridge disable
|
|
397
|
+
|
|
393
398
|
# 安全移除 Hooks、恢复 Claude status line,并清理 shell 集成
|
|
394
399
|
cc-pets uninstall
|
|
395
400
|
|
|
@@ -591,6 +596,8 @@ PetDex 官方 CLI(`npx petdex install <slug>`)会把素材放在 `~/.petdex/
|
|
|
591
596
|
- 状态气泡和通知只显示 Provider、状态及脱敏工具类别,不显示会话正文。
|
|
592
597
|
- 项目不上传会话内容、额度、凭据或使用统计,也不包含遥测服务。
|
|
593
598
|
- 右键“退出桌宠”或执行 `cc-pets uninstall` 后,不会继续运行后台守护进程。
|
|
599
|
+
- [CC Bridge](./CC_BRIDGE.zh-CN.md) 默认关闭;开启后,会话之间的消息正文会保存在当前用户的临时目录
|
|
600
|
+
(仅本人可读,24 小时过期),这是本项目唯一会保存正文的功能。
|
|
594
601
|
|
|
595
602
|
## 卸载
|
|
596
603
|
|
|
@@ -38,6 +38,19 @@
|
|
|
38
38
|
// 圆形状态图标右上角的待审批角标。状态卡正文永远跟着最新事件走,角标负责让
|
|
39
39
|
// "还有几个会话在等你确认"始终留在视线里。
|
|
40
40
|
@property NSView *approvalBadgeView;
|
|
41
|
+
// CC Bridge 消息角标(图标右下角)与其数据:会话名、最近送达、信箱积压。
|
|
42
|
+
// bridgeSeenAt 之后送达的消息算"未读",打开会话菜单即更新。
|
|
43
|
+
@property NSView *bridgeBadgeView;
|
|
44
|
+
@property NSTimeInterval bridgeSeenAt;
|
|
45
|
+
@property NSDictionary<NSString *, NSDictionary *> *bridgeSessions;
|
|
46
|
+
@property NSArray<NSDictionary *> *bridgeRecentDeliveries;
|
|
47
|
+
@property NSArray<NSDictionary *> *bridgeDeliveryCache;
|
|
48
|
+
@property NSDate *bridgeSentStamp;
|
|
49
|
+
@property NSDictionary<NSString *, NSNumber *> *bridgePendingCounts;
|
|
50
|
+
// 菜单开关触发的 cc-pets bridge 命令正在执行时为 YES,期间忽略新的切换,避免并发改配置。
|
|
51
|
+
@property BOOL bridgeCommandRunning;
|
|
52
|
+
// 已为哪个时间点之前的送达发过系统通知。
|
|
53
|
+
@property NSTimeInterval bridgeNotifiedAt;
|
|
41
54
|
@property BOOL statusBubbleExpanded;
|
|
42
55
|
@property BOOL statusBubbleAbove;
|
|
43
56
|
@property BOOL hasAgentStatus;
|