@raysonmeng/agentbridge 0.1.24 → 0.1.26

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 (9) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/README.md +115 -192
  3. package/README.zh-CN.md +112 -183
  4. package/dist/cli.js +4 -4
  5. package/dist/daemon.js +3 -3
  6. package/package.json +1 -1
  7. package/plugins/agentbridge/.claude-plugin/plugin.json +1 -1
  8. package/plugins/agentbridge/server/bridge-server.js +3 -3
  9. package/plugins/agentbridge/server/daemon.js +3 -3
package/.claude-plugin/marketplace.json CHANGED
@@ -12,7 +12,7 @@
12
12
  {
13
13
  "name": "agentbridge",
14
14
  "description": "Bridge Claude Code and Codex through a shared daemon, push channel delivery, and reply/get_messages tools.",
15
- "version": "0.1.24",
15
+ "version": "0.1.26",
16
16
  "author": {
17
17
  "name": "AgentBridge Contributors",
18
18
  "email": "raysonmeng@qq.com"
package/README.md CHANGED
@@ -7,12 +7,22 @@
7
7
 
8
8
  Local bridge for bidirectional communication between Claude Code and Codex inside the same working session.
9
9
 
10
- AgentBridge uses a two-process architecture:
10
+ What that buys you, concretely:
11
11
 
12
- - **bridge.ts** is the foreground MCP client started by Claude Code via the AgentBridge plugin
13
- - **daemon.ts** is a persistent local background process that owns the Codex app-server proxy and bridge state
12
+ - **Cross-review, not just cross-talk** — Codex implements; Claude reviews the diff in real time *inside the same session* and pushes its change requests straight back into Codex's thread. Two providers holding each other accountable, no copy-paste.
13
+ - **Task splits from one prompt** — ask either agent to propose a division of labor with the other, and they negotiate who does what before writing code. You steer; they coordinate.
14
+ - **Quota relay for overnight runs** — when one side's subscription window runs dry, it stops cleanly at a turn boundary and hands the task off to the other side, so a long job keeps moving instead of dying at a limit.
14
15
 
15
- When Claude Code closes, the foreground MCP process exits while the background daemon and Codex proxy keep running. When Claude Code starts again, it reconnects automatically with exponential backoff.
16
+ <!-- TODO: assets/demo.gif — see docs/demo/RECORDING.md -->
17
+
18
+ > **This tool was largely built by Claude Code and Codex collaborating through it.**
19
+ > **Every PR written by one agent was reviewed by the other.** AgentBridge is its own proof of concept.
20
+
21
+ ## Why not just…
22
+
23
+ - **…run two terminals and copy-paste?** You can — and you become the message bus, ferrying text by hand and eyeballing when it's safe to interrupt. AgentBridge automates the relay: messages flow on their own, a busy-guard blocks replies during an active turn, and noisy intermediate events are filtered so each side sees only the other's meaningful output.
24
+ - **…use a one-way delegation plugin?** Tools like `openai/codex-plugin-cc` let a host *call* Codex and get one answer back — request in, response out, no standing peer on the other side. AgentBridge keeps **both** agents live as persistent peers, and either side can push a message **mid-turn** (a review comment lands while the other is still working), not only at call boundaries.
25
+ - **…wire up an external orchestrator?** A god-process scheduling dumb terminals is top-down: one brain, N workers that never talk to each other. AgentBridge is peer-to-peer — two full agents converse in-session, propose their own splits, and review each other, with the human steering instead of scripting every hop.
16
26
 
17
27
  ## What this project is / is not
18
28
 
@@ -36,127 +46,84 @@ When Claude Code closes, the foreground MCP process exits while the background d
36
46
  - **Multiple pairs side by side** — one Claude+Codex pair per project directory, ports allocated per pair in +10 strides from 4500. Pair-aware `claude` / `codex` / `resume` / `kill` / `doctor` / `budget` via `--pair`.
37
47
  - **Resilient lifecycle** — a persistent background daemon survives Claude Code restarts (auto-reconnect with backoff); orphan-process cleanup; `abg doctor` read-only diagnostics; `abg pairs prune` reclaims stranded state.
38
48
  - **Thread auto-resume** — bare `abg codex` resumes the pair's last Codex thread; `abg resume` prints/performs the resume commands for both sides.
39
- - **Budget coordination, slowdown-line & fully-automatic resume** — keep a long task moving across subscription-quota windows instead of dying at a limit. See [Budget Coordination & Auto-Resume](#budget-coordination--auto-resume).
40
-
41
- ## Architecture
42
-
43
- ```
44
- ┌──────────────┐ MCP stdio / plugin ┌────────────────────┐
45
- │ Claude Code │ ──────────────────────────▶ │ bridge.ts │
46
- │ Session │ ◀────────────────────────── │ foreground client │
47
- └──────────────┘ └─────────┬──────────┘
48
- │
49
- │ control WS (:4502)
50
- ▼
51
- ┌────────────────────┐
52
- │ daemon.ts │
53
- │ bridge daemon │
54
- └─────────┬──────────┘
55
- │
56
- ws://127.0.0.1:4501 proxy
57
- │
58
- ▼
59
- ┌────────────────────┐
60
- │ Codex app-server │
61
- └────────────────────┘
62
- ```
63
-
64
- ### Data flow
65
-
66
- | Direction | Path |
67
- |-----------|------|
68
- | **Codex -> Claude** | `daemon.ts` captures `agentMessage` -> control WS -> `bridge.ts` -> `notifications/claude/channel` |
69
- | **Claude -> Codex** | Claude calls the `reply` tool -> `bridge.ts` -> control WS -> `daemon.ts` -> `turn/start` injects into the Codex thread |
70
-
71
- ### Loop prevention
72
-
73
- Each message carries a `source` field (`"claude"` or `"codex"`). The bridge never forwards a message back to its origin.
49
+ - **Budget coordination, slowdown-line & fully-automatic resume** — keep a long task moving across subscription-quota windows instead of dying at a limit. See [Budget Coordination](#budget-coordination--auto-resume).
74
50
 
75
51
  ## Prerequisites
76
52
 
77
53
  | Dependency | Version | Install |
78
54
  |-----------|---------|---------|
79
- | [Bun](https://bun.sh) | v1.0+ | `curl -fsSL https://bun.sh/install \| bash` |
55
+ | [Bun](https://bun.sh) | v1.3.11+ | `curl -fsSL https://bun.sh/install \| bash` |
80
56
  | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | v2.1.80+ | `npm install -g @anthropic-ai/claude-code` |
81
57
  | [Codex CLI](https://github.com/openai/codex) | latest | `npm install -g @openai/codex` |
82
58
 
83
- > **Note:** Bun is required as the runtime for the AgentBridge daemon and plugin server. Node.js alone is not sufficient.
59
+ > **Bun is required** as the runtime for the AgentBridge daemon and plugin server. Node.js alone is not enough — if `abg` installs but won't run, you're almost certainly missing Bun (see [Troubleshooting](docs/TROUBLESHOOTING.md)).
84
60
 
85
61
  ## Quick Start
86
62
 
87
- ### Install via Plugin Marketplace (recommended)
88
-
89
- Install AgentBridge directly from Claude Code using the plugin marketplace:
63
+ Four steps from nothing to a running pair:
90
64
 
91
65
  ```bash
92
- # 1. In Claude Code, add the AgentBridge marketplace
93
- /plugin marketplace add raysonmeng/agent-bridge
94
-
95
- # 2. Install the plugin
96
- /plugin install agentbridge@agentbridge
66
+ # 1. Install Bun (the runtime — Node alone won't work)
67
+ curl -fsSL https://bun.sh/install | bash
97
68
 
98
- # 3. Reload plugins to activate
99
- /reload-plugins
100
- ```
101
-
102
- Then install the CLI tool:
103
-
104
- ```bash
105
- # 4. Install the CLI globally
69
+ # 2. Install the CLI. postinstall auto-registers the Claude Code plugin
70
+ # marketplace AND installs the plugin (best-effort; needs bun + claude present).
106
71
  npm install -g @raysonmeng/agentbridge
107
72
 
108
- # 5. Generate project config (optional)
109
- abg init
110
-
111
- # 6. Start Claude Code with AgentBridge channel enabled
73
+ # 3. Start Claude Code with the AgentBridge channel enabled
112
74
  abg claude
113
75
 
114
- # 7. Start Codex TUI connected to the bridge (in another terminal)
76
+ # 4. In another terminal, start Codex TUI connected to the same bridge
115
77
  abg codex
116
78
  ```
117
79
 
118
- > **Tip:** `abg` is a short alias for `agentbridge`. Both commands are identical — use whichever you prefer.
80
+ That's it — the daemon starts automatically when needed and reconnects if restarted. (`abg` is a short alias for `agentbridge`; both are identical.) If the postinstall plugin step was skipped (e.g. Claude Code wasn't installed yet), run `abg init` to retry it, or see the [manual install fallback](#manual-plugin-install-fallback).
81
+
82
+ > [!WARNING]
83
+ > **`abg claude` launches with `--dangerously-skip-permissions` and `abg codex` launches with `--yolo` by default.** This is deliberate — an unattended agent pair can't stop to ask you for each permission — but it means both agents can run commands and edit files **without prompting**. Only do this in a workspace you trust. To launch with normal prompts, add `--safe` (`abg claude --safe`, `abg codex --safe`) or set `AGENTBRIDGE_SAFE=1`. The defaults are also auto-suppressed if you pass your own permission flags.
84
+
85
+ ### Your first collaboration
86
+
87
+ With both sides running, give Claude a task that wants a second agent, e.g.:
119
88
 
120
- That's it. The daemon starts automatically when needed and reconnects if restarted.
89
+ > **Ask Claude:** *"Propose a task split with Codex for &lt;your task&gt;, then have Codex implement its part while you review."*
121
90
 
122
- #### Updating the plugin
91
+ You should see Claude send a proposed division of labor into Codex's session, Codex accept (or counter) and start working, and Codex's completion push back into Claude's session for review — all without you relaying anything by hand.
123
92
 
124
- When a new version is released, update from Claude Code:
93
+ ### Manual plugin install (fallback)
94
+
95
+ If the automatic postinstall didn't register the plugin, do it from inside Claude Code:
125
96
 
126
97
  ```bash
127
- /plugin marketplace update agentbridge
98
+ # 1. Add the AgentBridge marketplace
99
+ /plugin marketplace add raysonmeng/agent-bridge
100
+
101
+ # 2. Install the plugin
102
+ /plugin install agentbridge@agentbridge
103
+
104
+ # 3. Reload plugins to activate
128
105
  /reload-plugins
129
106
  ```
130
107
 
131
- Or enable auto-update: run `/plugin` → **Marketplaces** tab → select **agentbridge** → **Enable auto-update**.
108
+ To update later: `/plugin marketplace update agentbridge` then `/reload-plugins` (or enable auto-update under `/plugin` → **Marketplaces** → **agentbridge**).
132
109
 
133
110
  ### Install for local development
134
111
 
135
112
  If you want to modify AgentBridge source code, use the local development setup instead:
136
113
 
137
114
  ```bash
138
- # 1. Clone and install dependencies
139
115
  git clone https://github.com/raysonmeng/agent-bridge.git
140
116
  cd agent-bridge
141
117
  bun install
142
118
  bun link
143
119
 
144
- # 2. Set up local plugin + project config
145
120
  agentbridge dev # Register local marketplace + install plugin
146
121
  agentbridge init # Check dependencies, generate .agentbridge/config.json
147
-
148
- # 3. Start Claude Code with AgentBridge plugin loaded
149
- agentbridge claude
150
-
151
- # 4. Start Codex TUI connected to the bridge (in another terminal)
152
- agentbridge codex
122
+ agentbridge claude # Start Claude Code with plugin loaded
123
+ agentbridge codex # (another terminal) Start Codex TUI connected to the bridge
153
124
  ```
154
125
 
155
- > **Note:** `agentbridge claude` injects `--dangerously-load-development-channels plugin:agentbridge@agentbridge` automatically. This loads a local development channel into Claude Code (currently a Research Preview workflow). Only enable channels and MCP servers you trust.
156
-
157
- #### Updating after code changes
158
-
159
- After modifying AgentBridge source code, re-run `agentbridge dev` to sync changes to the plugin cache, then restart Claude Code or run `/reload-plugins` in an active session.
126
+ > **Note:** `agentbridge claude` injects `--dangerously-load-development-channels plugin:agentbridge@agentbridge` (a Research Preview workflow). Only enable channels and MCP servers you trust. After changing source, re-run `agentbridge dev` and restart Claude Code (or `/reload-plugins`).
160
127
 
161
128
  ## CLI Reference
162
129
 
@@ -166,16 +133,19 @@ After modifying AgentBridge source code, re-run `agentbridge dev` to sync change
166
133
  |---------|-------------|
167
134
  | `abg init` | Install plugin, check dependencies (bun/claude/codex), generate `.agentbridge/config.json` |
168
135
  | `abg claude [args...]` | Start Claude Code with push channel enabled. **Runs with `--dangerously-skip-permissions` by default** (opt out: `--safe` or `AGENTBRIDGE_SAFE=1`). Clears any killed sentinel from a previous `kill`. Pass-through args are forwarded to `claude` |
169
- | `abg codex [args...]` | Start Codex TUI connected to AgentBridge daemon. **Bare `abg codex` auto-resumes the pair's last thread; use `abg codex --new` for a fresh thread. TUI launches run with `--yolo` by default** (opt out: `--safe` or `AGENTBRIDGE_SAFE=1`; non-TUI subcommands like `exec` are never touched). Manages TUI process lifecycle (pid tracking, cleanup). Pass-through args forwarded to `codex` |
170
- | `abg resume [claude\|codex]` | No target: print the resume commands for this directory's last Claude Code session and this pair's current Codex thread. With a target: resume that side directly (delegates to `abg claude --resume <id>` / `abg codex resume-current`) |
171
- | `abg pairs` | List registered pairs; `abg pairs rm <name\|id>` removes one; `abg pairs prune` previews reclaimable orphan dirs + stranded registry entries (cwd-gone, dead, >1 day), `abg pairs prune --apply` deletes them |
136
+ | `abg codex [args...]` | Start Codex TUI connected to AgentBridge daemon. **Bare `abg codex` auto-resumes the pair's last thread; use `abg codex --new` for a fresh thread. TUI launches run with `--yolo` by default** (opt out: `--safe` or `AGENTBRIDGE_SAFE=1`; non-TUI subcommands like `exec` are never touched). Pass-through args forwarded to `codex` |
137
+ | `abg resume [claude\|codex]` | No target: print the resume commands for this directory's last Claude session and this pair's current Codex thread. With a target: resume that side directly |
138
+ | `abg pairs` | List registered pairs; `abg pairs rm <name\|id>` removes one; `abg pairs prune` previews reclaimable orphan dirs + stranded registry entries, `--apply` deletes them |
172
139
  | `abg doctor [--json]` | Read-only diagnosis: env, daemon health/readiness, build drift, artifact alignment, TUI attachment, logs |
173
140
  | `abg budget [--json]` | Both agents' subscription quota snapshot (5h/weekly windows, drift, pause state) |
174
141
  | `abg logs [--codex] [-f] [-n N]` | Tail this pair's daemon log (or the Codex wrapper log with `--codex`); `-f` follows, `-n N` sets the line count (default 100) |
175
142
  | `abg kill` | Gracefully stop this pair's daemon and managed Codex TUI, write killed sentinel; `abg kill --all` stops every pair |
176
143
  | `abg dev` | (Dev only) Register local marketplace + force-sync plugin to cache |
177
- | `abg --help` | Show help |
178
- | `abg --version` | Show version |
144
+ | `abg --help` / `abg --version` | Show help / version |
145
+
146
+ ### Cross-network collaboration *(v3 preview)*
147
+
148
+ The v3 collaboration layer (shared rooms across machines/agents over a broker — `auth`, `broker`, `room`, `join`, `publish`) is in preview on the [`integration/v3-all`](https://github.com/quilin-ai/agent-bridge/tree/integration/v3-all) branch and lands here with v3. Spec: [docs/09-v3协作系统规格.md](docs/09-v3协作系统规格.md).
179
149
 
180
150
  The pair-aware commands (`claude`, `codex`, `resume`, `kill`, `doctor`, `budget`, `logs`) accept `--pair <name>` to target a specific pair — one pair per project directory by default, with ports allocated per pair in +10 strides from 4500.
181
151
 
@@ -187,16 +157,48 @@ Some flags are automatically injected and cannot be manually specified:
187
157
  - `agentbridge codex` owns: `--remote`, `--enable tui_app_server`
188
158
  - Both launchers consume the wrapper flag `--safe` (it is never forwarded): it disables the max-permission defaults for that launch. The defaults are also auto-suppressed when you pass any explicit permission flag yourself (`-a`/`--ask-for-approval`/`-s`/`--sandbox` for codex; `--permission-mode`/`--allow-dangerously-skip-permissions` for claude) — injecting `--yolo` next to an explicit approval policy is a hard codex CLI conflict.
189
159
 
190
- Passing these flags manually will result in a hard error with guidance to use the native command directly.
160
+ Passing an owned flag manually is a hard error with guidance to use the native command directly.
161
+
162
+ > **Note on flag positioning for `agentbridge codex`:** for the bare TUI form, bridge flags are injected at the front; for TUI subcommands that carry per-subcommand args (`resume`, `fork`), they are injected *after* the subcommand name; non-TUI subcommands (`exec`, `mcp`, `plugin`, …) are passed through unchanged. See `src/cli/codex.ts buildCodexArgs`.
163
+
164
+ ## Architecture
165
+
166
+ AgentBridge is a **two-process** local bridge:
167
+
168
+ - **bridge.ts** — the foreground MCP client started by Claude Code via the AgentBridge plugin. It exits when Claude Code closes.
169
+ - **daemon.ts** — a persistent local background process that owns the Codex app-server proxy and the single source of truth for bridge state. It survives Claude Code restarts; `bridge.ts` reconnects with exponential backoff.
170
+
171
+ ```
172
+ ┌──────────────┐ MCP stdio / plugin ┌────────────────────┐
173
+ │ Claude Code │ ──────────────────────────▶ │ bridge.ts │
174
+ │ Session │ ◀────────────────────────── │ foreground client │
175
+ └──────────────┘ └─────────┬──────────┘
176
+ │
177
+ │ control WS (:4502)
178
+ ▼
179
+ ┌────────────────────┐
180
+ │ daemon.ts │
181
+ │ bridge daemon │
182
+ └─────────┬──────────┘
183
+ │
184
+ ws://127.0.0.1:4501 proxy
185
+ │
186
+ ▼
187
+ ┌────────────────────┐
188
+ │ Codex app-server │
189
+ └────────────────────┘
190
+ ```
191
+
192
+ ### Data flow
191
193
 
192
- > **Note on flag positioning for `agentbridge codex`:** For the bare TUI form
193
- > (`agentbridge codex …`), bridge flags are injected at the front. For TUI
194
- > subcommands that carry per-subcommand args (`resume`, `fork`), they are
195
- > injected *after* the subcommand name (so clap parses them as options of the
196
- > actually-invoked command, not the root). Non-TUI subcommands like `exec`,
197
- > `mcp`, `plugin`, `remote-control`, `update` etc. are passed through
198
- > unchanged — no bridge flags injected. See `src/cli/codex.ts buildCodexArgs`
199
- > for the full positioning logic.
194
+ | Direction | Path |
195
+ |-----------|------|
196
+ | **Codex -> Claude** | `daemon.ts` captures `agentMessage` -> control WS -> `bridge.ts` -> `notifications/claude/channel` |
197
+ | **Claude -> Codex** | Claude calls the `reply` tool -> `bridge.ts` -> control WS -> `daemon.ts` -> `turn/start` injects into the Codex thread |
198
+
199
+ ### Loop prevention
200
+
201
+ Each message carries a `source` field (`"claude"` or `"codex"`). The bridge never forwards a message back to its origin.
200
202
 
201
203
  ## Project Config
202
204
 
@@ -208,60 +210,6 @@ Running `agentbridge init` creates a `.agentbridge/` directory in your project r
208
210
 
209
211
  The config is loaded by the CLI and daemon at startup. Re-running `init` is idempotent and will not overwrite existing files.
210
212
 
211
- ## File Structure
212
-
213
- ```
214
- agent_bridge/
215
- ├── .github/
216
- │ ├── ISSUE_TEMPLATE/ # Bug report and feature request templates
217
- │ ├── pull_request_template.md
218
- │ └── workflows/ci.yml # GitHub Actions CI
219
- ├── assets/ # Static assets (images, etc.)
220
- ├── docs/ # Project growth timeline (stages 01-09; index: docs/README.md)
221
- │ ├── 01-起步与v1协作核心.md # Stage 1: bidirectional bridge + v1 collaboration core
222
- │ ├── 02-Phase3产品化.md # Stage 2: two-process architecture + CLI + plugin
223
- │ ├── …(03-08) # release / reliability / multi-pair / protocol v2 / budget / v2 vision
224
- │ └── 09-v3协作系统规格.md # Stage 9: latest v3 cross-network collaboration spec
225
- ├── plugins/agentbridge/ # Claude Code plugin bundle
226
- │ ├── .claude-plugin/plugin.json
227
- │ ├── commands/init.md
228
- │ ├── hooks/hooks.json
229
- │ ├── scripts/health-check.sh
230
- │ └── server/ # Bundled bridge-server.js + daemon.js
231
- ├── src/
232
- │ ├── bridge.ts # Claude foreground MCP client (plugin entry point)
233
- │ ├── daemon.ts # Persistent background daemon
234
- │ ├── daemon-client.ts # WebSocket client for daemon control port
235
- │ ├── daemon-lifecycle.ts # Shared daemon lifecycle (ensureRunning, kill, startup lock)
236
- │ ├── control-protocol.ts # Foreground/background control protocol types
237
- │ ├── claude-adapter.ts # MCP server adapter for Claude Code channels
238
- │ ├── codex-adapter.ts # Codex app-server WebSocket proxy and message interception
239
- │ ├── config-service.ts # Project config (.agentbridge/) read/write
240
- │ ├── state-dir.ts # Platform-aware state directory resolver
241
- │ ├── message-filter.ts # Smart message filtering (markers, summary buffer)
242
- │ ├── types.ts # Shared types
243
- │ ├── cli.ts # CLI entry point and command router
244
- │ └── cli/
245
- │ ├── init.ts # agentbridge init
246
- │ ├── claude.ts # agentbridge claude
247
- │ ├── codex.ts # agentbridge codex
248
- │ ├── pairs.ts # agentbridge pairs (list / rm / prune)
249
- │ ├── doctor.ts # agentbridge doctor (read-only diagnosis)
250
- │ ├── budget.ts # agentbridge budget (quota snapshot)
251
- │ ├── kill.ts # agentbridge kill
252
- │ ├── pkg-root.ts # package-root resolution helper
253
- │ └── dev.ts # agentbridge dev
254
- ├── CLAUDE.md # Project rules for AI agents
255
- ├── CODE_OF_CONDUCT.md
256
- ├── CONTRIBUTING.md
257
- ├── LICENSE
258
- ├── README.md
259
- ├── README.zh-CN.md
260
- ├── SECURITY.md
261
- ├── package.json
262
- └── tsconfig.json
263
- ```
264
-
265
213
  ## Configuration
266
214
 
267
215
  ### Environment Variables
@@ -283,15 +231,7 @@ agent_bridge/
283
231
 
284
232
  ### Update notifications
285
233
 
286
- `abg claude` and `abg codex` print a one-line notice to stderr when a newer **stable** AgentBridge is published to npm, e.g.:
287
-
288
- ```
289
- ⚠ AgentBridge update available: 0.1.6 → 0.1.7
290
- CLI: npm install -g @raysonmeng/agentbridge@latest
291
- Plugin: /plugin marketplace update agentbridge (then /reload-plugins)
292
- ```
293
-
294
- The check is best-effort: the notice is printed from a cached result, the npm check runs at most once per day in the background, and any network/registry failure is silently ignored. On an interactive TTY, a cached update prompts before launch; answering `y` runs `npm install -g @raysonmeng/agentbridge@latest`, while `N` (or no answer within 15 seconds) records that version as dismissed and continues launching. Non-interactive output and CI never prompt, and the notice can be disabled with `NO_UPDATE_NOTIFIER=1` or kept notice-only with `AGENTBRIDGE_UPDATE_PROMPT=0`.
234
+ `abg claude` and `abg codex` print a one-line notice to stderr when a newer **stable** AgentBridge is published to npm. The check is best-effort: printed from a cached result, the npm check runs at most once per day in the background, and any network/registry failure is silently ignored. On an interactive TTY, a cached update prompts before launch; answering `y` runs the upgrade, while `N` (or no answer within 15 seconds) dismisses that version and continues. Disable with `NO_UPDATE_NOTIFIER=1`, or keep notice-only with `AGENTBRIDGE_UPDATE_PROMPT=0`.
295
235
 
296
236
  ### State Directory
297
237
 
@@ -304,58 +244,41 @@ The daemon stores runtime state in a platform-aware directory:
304
244
 
305
245
  Contents: `daemon.pid`, `status.json`, `agentbridge.log`, `killed` (sentinel), `startup.lock`
306
246
 
307
- ### Disabled Bridge States
308
-
309
- The bridge can enter several dormant states when it cannot accept new MCP replies. Each state surfaces to the agent as an error message (and, for the transient ones, an in-band push notification):
310
-
311
- | State | Cause | Recovery |
312
- |-------|-------|----------|
313
- | `killed` | `agentbridge kill` was run, sentinel file present. | Restart Claude Code (`agentbridge claude`), switch to a new conversation, or run `/resume`. |
314
- | `rejected` | Daemon rejected the connection: another Claude session is already attached. | Close the other session, or run `agentbridge kill` to reset, then `agentbridge claude` again. |
315
- | `evicted` | A newer session evicted this one after the incumbent failed a liveness probe (issue #68). | Close this session and start a fresh one with `agentbridge claude`. |
316
- | `probe_in_progress` | A liveness probe is currently checking the incumbent — contention window. Transient (auto-recovers within `DISABLED_RECOVERY_INTERVAL_MS` × cap, ~30 s). | None needed; the recovery poller reconnects automatically when the slot clears. |
317
- | `auto_recovery_exhausted` | The auto-recovery poller for `probe_in_progress` ran its full retry budget (6 attempts, ~30 s) without succeeding. Terminal. | Retry manually with `agentbridge claude`. |
318
-
319
247
  ## Budget Coordination & Auto-Resume
320
248
 
321
- AgentBridge can keep a long task moving across subscription-quota windows instead of letting it die when one agent hits its limit. This whole capability is driven by the companion **agent-quota-guard** tool: the bridge reads its quota probe and its `pending` records — install the guard to enable it.
322
-
323
- The daemon's budget coordinator polls **both** agents' account-level 5h/weekly quota (via the guard's probe) and coordinates the two sides; `abg budget [--json]` prints the live snapshot (both windows, drift, pause state). With the guard installed, two further capabilities activate:
324
-
325
- - **Slowdown-line — no mid-task cut.** Near the quota hard-line the guard does NOT deny mid-tool-call. Instead it surfaces a reminder, lets the current turn finish, then stops cleanly at the turn boundary, writes a `.agent/checkpoint.md`, and drops a `pending` record the bridge detects.
326
- - **Fully-automatic resume after the window refreshes.** When a paused side's quota window refreshes, the bridge resumes the task **in the original interactive TUI** — no headless background process, no manual step:
327
- - **Codex** — a queued `turn/start` injection (`ResumeInjectionQueue`) opens a fresh turn that continues from the checkpoint. Fully automatic.
328
- - **Claude** — a channel push carrying a stable `resume_id`; Claude echoes it back via the `ack_resume` MCP tool. Unacked pushes retry with a fresh delivery id (stable `resume_id`); after retries are exhausted a `SessionStart` degrade-sentinel surfaces a recovery hint the next session reads.
329
- - **Idempotency** — per-pending claim/consumed tombstones (a sha256 of agent + session + cwd + content hash) ensure a given resume is injected at most once, even across daemon restarts; stale tombstones are TTL-pruned.
249
+ AgentBridge can keep a long task moving across subscription-quota windows instead of letting it die when one agent hits its limit. The capability is driven by the companion tool **[agent-quota-guard](https://www.npmjs.com/package/agent-quota-guard)** ([repo](https://github.com/raysonmeng/agent-quota-guard) · v0.2.0, 2026-06-13) — install the guard to enable it.
330
250
 
331
- Coordination directives the bridge may emit while a task runs: **balance** (route more work to the side with more runway / remaining work-time), **underutilized** (the account will not use its weekly quota before reset — split more parallel subtasks / raise delegation density), and **pause / handoff / resume**.
251
+ - **Snapshot** — the daemon polls both agents' account-level 5h/weekly quota via the guard's probe; `abg budget [--json]` prints the live snapshot (both windows, drift, pause state). This works with just the guard's probe.
252
+ - **Slowdown-line (no mid-task cut)** — near the quota hard-line the guard does *not* deny mid-tool-call; it lets the current turn finish, stops cleanly at the turn boundary, writes a `.agent/checkpoint.md`, and drops a `pending` record the bridge detects.
253
+ - **Automatic resume** — when the paused side's window refreshes, the bridge resumes the task **in the original interactive TUI**: Codex via a queued `turn/start` injection, Claude via a channel push it acks with `ack_resume`. Per-pending idempotency tombstones ensure a resume is injected at most once, even across daemon restarts.
332
254
 
333
- > Slowdown-line + auto-resume are an opt-in, companion-guard feature. The Claude-side resume is best-effort (ack + retry + a SessionStart fallback): channel pushes to a fully idle session have known upstream variability, so the bridge only marks a side resumed once it sees a real `ack_resume`.
255
+ > **Experimental / opt-in.** This is a companion-guard feature. The Claude-side resume is best-effort (ack + retry + a `SessionStart` fallback): channel pushes to a fully idle session have known upstream variability, so the bridge only marks a side resumed once it sees a real `ack_resume`.
334
256
 
335
257
  ## Current Limitations
336
258
 
337
259
  - Only forwards `agentMessage` items, not intermediate `commandExecution`, `fileChange`, or similar events
338
260
  - Single Codex thread per pair, no multi-session support within a pair yet
339
261
  - Single Claude foreground connection per pair; a new Claude session replaces the previous one
340
- - Multiple pairs run side-by-side on one machine (one per project directory, per-pair port allocation); Windows is not an officially supported platform yet
262
+ - Multiple pairs run side-by-side on one machine (one per project directory); Windows is not an officially supported platform yet
341
263
 
342
- ### Codex git restrictions
264
+ For dormant/disabled bridge states, the Codex `.git` restriction, and other gotchas, see **[Troubleshooting](docs/TROUBLESHOOTING.md)**.
343
265
 
344
- Codex runs in a sandboxed environment that **blocks all writes to the `.git` directory**. This means Codex cannot run `git commit`, `git push`, `git pull`, `git checkout -b`, `git merge`, or any other command that modifies git metadata. Attempting these commands will cause the Codex session to hang indefinitely.
266
+ ## Roadmap
345
267
 
346
- **Recommendation:** Let Claude Code handle all git operations (branching, committing, pushing, creating PRs). Codex should focus on code changes and report completed work via `agentMessage`, then Claude Code takes care of the git workflow.
268
+ - **More adapters** — AgentBridge wires Claude Code ↔ Codex today. Candidates for the next agent: **OpenCode, OpenClaw, Hermes Agent, Gemini CLI**. Vote in the [adapter roadmap issue](https://github.com/quilin-ai/agent-bridge/issues/212).
269
+ - **Capability mesh** — beyond messaging: connected agents will publish their commands / skills / MCP tools so a peer can invoke them directly — moving from *messaging* to *capability invocation*.
270
+ - **v2 — multi-agent foundation** (partly landed): room-scoped collaboration, stable identity, a formal control protocol, stronger recovery. See [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md).
271
+ - **v3 — cross-network collaboration** (preview on the [`integration/v3-all`](https://github.com/quilin-ai/agent-bridge/tree/integration/v3-all) branch): shared rooms across machines and agents over a broker. See [docs/09-v3协作系统规格.md](docs/09-v3协作系统规格.md).
347
272
 
348
- ## Roadmap
273
+ ## Docs
349
274
 
350
- - **v1.x (current)**: Improve the single-bridge experience without architectural refactoring -- less noise, better turn discipline, and clearer collaboration modes. See [docs/01-起步与v1协作核心.md](docs/01-起步与v1协作核心.md).
351
- - **v2 (planned)**: Introduce the multi-agent foundation -- room-scoped collaboration, stable identity, a formal control protocol, and stronger recovery semantics. See [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md).
352
- - **v3+ (longer term)**: Explore smarter collaboration, richer policies, and more advanced orchestration across runtimes.
275
+ - **[Troubleshooting](docs/TROUBLESHOOTING.md)** — disabled-state recovery, the Codex `.git` hang, "installed but won't run", Bun version requirements
276
+ - **[User manual (EN)](https://github.com/quilin-ai/agent-bridge/blob/integration/v3-all/docs/manual/manual-en.md)** — end-to-end usage walkthrough
277
+ - **[Project growth timeline](docs/README.md)** — how AgentBridge was built, stage by stage (01–11)
353
278
 
354
279
  ## How This Project Was Built
355
280
 
356
- This project was built collaboratively by **Claude Code** (Anthropic) and **Codex** (OpenAI), communicating through AgentBridge itself -- the very tool they were building together. A human developer coordinated the effort, assigning tasks, reviewing progress, and directing the two agents to work in parallel and review each other's output.
357
-
358
- In other words, AgentBridge is its own proof of concept: two AI agents from different providers, connected in real time, shipping code side by side.
281
+ This project was built collaboratively by **Claude Code** (Anthropic) and **Codex** (OpenAI), communicating through AgentBridge itself — the very tool they were building together. A human developer coordinated the effort: assigning tasks, reviewing progress, and directing the two agents to work in parallel and review each other's output. Two AI agents from different providers, connected in real time, shipping code side by side.
359
282
 
360
283
  ## Contact
361
284
 
package/README.zh-CN.md CHANGED
@@ -7,12 +7,22 @@ English version: [README.md](README.md)
7
7
 
8
8
  让 Claude Code 和 Codex 在同一个工作会话中进行双向通信的本地 Bridge。
9
9
 
10
- AgentBridge 采用两层进程结构：
10
+ 具体能换来什么：
11
11
 
12
- - **bridge.ts** 是由 Claude Code 通过 AgentBridge 插件启动的前台 MCP 客户端
13
- - **daemon.ts** 是常驻本地的后台进程，持有 Codex app-server 代理和桥接状态
12
+ - **不只是互相说话，是互相 review** —— Codex 写实现，Claude 在**同一会话内**实时 review 这个 diff，并把修改意见直接推回 Codex 的 thread。两家模型互相盯着对方，不用复制粘贴。
13
+ - **一句 prompt 完成分工** —— 让任一侧提出与对方的分工方案，两个 agent 先商量好谁做什么再动手写代码。你把舵，它们协调。
14
+ - **通宵任务的额度接力** —— 一侧订阅额度窗口烧到线时，它在回合边界干净停下，把任务交接给另一侧，让长任务继续跑,而不是撞到上限就死掉。
14
15
 
15
- 当 Claude Code 关闭时，前台 MCP 进程退出，后台 daemon 与 Codex 代理继续存活。当 Claude Code 再次启动时，会自动重连（指数退避）。
16
+ <!-- TODO: assets/demo.gif — see docs/demo/RECORDING.md -->
17
+
18
+ > **这个工具很大程度上就是 Claude Code 和 Codex 通过它本身协作写出来的。**
19
+ > **一个 agent 写的每个 PR,都由另一个 agent review。** AgentBridge 就是它自己的 proof of concept。
20
+
21
+ ## Why not just…（换个方案不行吗)
22
+
23
+ - **……开两个终端手动复制粘贴?** 可以——但你就成了消息总线,手动搬运文本、靠肉眼判断什么时候能插话。AgentBridge 把这套中转自动化了:消息自己流动,busy-guard 在活跃 turn 期间挡住回复,噪声中间事件被过滤,每一侧只看到对方有意义的输出。
24
+ - **……用一个单向委派插件?** 像 `openai/codex-plugin-cc` 这类工具,是宿主**调用** Codex、拿回一个答案——问进去、答出来,对面没有一个常驻的对等体。AgentBridge 让**两个** agent 都作为常驻对等体活着,任一侧都能在**回合中途**推消息(review 意见在对方还在干活时就落进它会话),而不只是在调用边界。
25
+ - **……接一个外部编排器?** 一个上帝进程调度哑终端是自上而下的:一个大脑、N 个互不说话的 worker。AgentBridge 是对等的——两个完整 agent 在会话内对话、自己提分工、互相 review,人在旁边把舵,而不是脚本化每一跳。
16
26
 
17
27
  ## 这个项目是什么 / 不是什么
18
28
 
@@ -38,125 +48,82 @@ AgentBridge 采用两层进程结构：
38
48
  - **Thread 自动续接**：裸 `abg codex` 续接该对上次的 Codex thread；`abg resume` 打印/执行两侧的续接命令。
39
49
  - **额度协调、减速线与全自动续接**：让长任务跨订阅额度窗口持续推进，而不是撞到上限就中断。见 [额度协调与自动续接](#额度协调与自动续接)。
40
50
 
41
- ## 架构
42
-
43
- ```
44
- ┌──────────────┐ MCP stdio / plugin ┌────────────────────┐
45
- │ Claude Code │ ─────────────────────────▶ │ bridge.ts │
46
- │ Session │ ◀───────────────────────── │ 前台 MCP 客户端 │
47
- └──────────────┘ └─────────┬──────────┘
48
- │
49
- │ 控制 WS (:4502)
50
- ▼
51
- ┌────────────────────┐
52
- │ daemon.ts │
53
- │ 常驻后台桥接进程 │
54
- └─────────┬──────────┘
55
- │
56
- ws://127.0.0.1:4501 proxy
57
- │
58
- ▼
59
- ┌────────────────────┐
60
- │ Codex app-server │
61
- └────────────────────┘
62
- ```
63
-
64
- ### 数据流
65
-
66
- | 方向 | 链路 |
67
- |------|------|
68
- | **Codex -> Claude** | `daemon.ts` 捕获 `agentMessage` -> 控制 WS -> `bridge.ts` -> `notifications/claude/channel` |
69
- | **Claude -> Codex** | Claude 调用 `reply` tool -> `bridge.ts` -> 控制 WS -> `daemon.ts` -> `turn/start` 注入 Codex thread |
70
-
71
- ### 防循环
72
-
73
- 每条消息都携带 `source` 字段（`"claude"` 或 `"codex"`），Bridge 永远不会把消息转发回它的来源。
74
-
75
51
  ## 前置条件
76
52
 
77
53
  | 依赖 | 版本 | 安装方式 |
78
54
  |------|------|----------|
79
- | [Bun](https://bun.sh) | v1.0+ | `curl -fsSL https://bun.sh/install \| bash` |
55
+ | [Bun](https://bun.sh) | v1.3.11+ | `curl -fsSL https://bun.sh/install \| bash` |
80
56
  | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | v2.1.80+ | `npm install -g @anthropic-ai/claude-code` |
81
57
  | [Codex CLI](https://github.com/openai/codex) | latest | `npm install -g @openai/codex` |
82
58
 
83
- > **注意：** Bun 是 AgentBridge daemon 和插件服务器的必要运行时，仅有 Node.js 不够。
59
+ > **Bun 是必要运行时**（AgentBridge daemon 和插件服务器都跑在 Bun 上），仅有 Node.js 不够——如果 `abg` 装上了却跑不起来，八成就是缺 Bun（见 [排错](docs/TROUBLESHOOTING.md)）。
84
60
 
85
61
  ## Quick Start
86
62
 
87
- ### 通过插件市场安装（推荐）
88
-
89
- 在 Claude Code 中直接安装 AgentBridge 插件：
63
+ 从零到一对跑起来，四步：
90
64
 
91
65
  ```bash
92
- # 1. 在 Claude Code 中，添加 AgentBridge 市场
93
- /plugin marketplace add raysonmeng/agent-bridge
94
-
95
- # 2. 安装插件
96
- /plugin install agentbridge@agentbridge
66
+ # 1. 装 Bun（运行时——只有 Node 不行）
67
+ curl -fsSL https://bun.sh/install | bash
97
68
 
98
- # 3. 重新加载插件以激活
99
- /reload-plugins
100
- ```
101
-
102
- 然后安装 CLI 工具：
103
-
104
- ```bash
105
- # 4. 全局安装 CLI
69
+ # 2. 装 CLI。postinstall 会自动注册 Claude Code 插件市场并安装插件
70
+ # （best-effort;需要本机已有 bun + claude）。
106
71
  npm install -g @raysonmeng/agentbridge
107
72
 
108
- # 5. 生成项目配置（可选）
109
- abg init
110
-
111
- # 6. 启动 Claude Code（自动加载 AgentBridge channel）
73
+ # 3. 启动 Claude Code 并启用 AgentBridge channel
112
74
  abg claude
113
75
 
114
- # 7. 在另一个终端启动 Codex TUI 连接 Bridge
76
+ # 4. 在另一个终端启动 Codex TUI 连接同一个 bridge
115
77
  abg codex
116
78
  ```
117
79
 
118
- > **提示：** `abg` 是 `agentbridge` 的简写别名，两个命令完全等价，用哪个都行。
80
+ 就这样——daemon 会在需要时自动启动，重启后自动重连。（`abg` 是 `agentbridge` 的简写别名，两者完全等价。）如果 postinstall 的插件步骤被跳过（比如当时还没装 Claude Code），运行 `abg init` 重试，或见 [手动安装插件（兜底）](#手动安装插件兜底)。
81
+
82
+ > [!WARNING]
83
+ > **`abg claude` 默认带 `--dangerously-skip-permissions` 启动，`abg codex` 默认带 `--yolo` 启动。** 这是故意的——无人值守的 agent 对没法为每个权限停下来问你——但这意味着两个 agent 都能**不经询问**执行命令、改文件。只在你信任的工作区里这么用。要恢复正常询问，加 `--safe`（`abg claude --safe`、`abg codex --safe`）或设 `AGENTBRIDGE_SAFE=1`；你自己显式传权限参数时,默认值也会被自动抑制。
84
+
85
+ ### 你的第一次协作
86
+
87
+ 两侧都跑起来后，给 Claude 一个需要第二个 agent 的任务，例如：
119
88
 
120
- 就这样。Daemon 会在需要时自动启动，重启后自动重连。
89
+ > **对 Claude 说：** *「为 &lt;你的任务&gt; 和 Codex 提一个分工方案，然后让 Codex 实现它那部分、你来 review。」*
121
90
 
122
- #### 更新插件
91
+ 你应该会看到：Claude 把一个分工提案发进 Codex 会话、Codex 接受（或反提议）并开始干活、Codex 完成后推回 Claude 会话让它 review——全程不用你手动中转任何东西。
123
92
 
124
- 新版本发布后，在 Claude Code 中更新：
93
+ ### 手动安装插件（兜底）
94
+
95
+ 如果自动 postinstall 没能注册插件，在 Claude Code 里手动来：
125
96
 
126
97
  ```bash
127
- /plugin marketplace update agentbridge
98
+ # 1. 添加 AgentBridge 市场
99
+ /plugin marketplace add raysonmeng/agent-bridge
100
+
101
+ # 2. 安装插件
102
+ /plugin install agentbridge@agentbridge
103
+
104
+ # 3. 重新加载插件以激活
128
105
  /reload-plugins
129
106
  ```
130
107
 
131
- 或启用自动更新：执行 `/plugin` → **Marketplaces** 标签页 → 选择 **agentbridge** → **Enable auto-update**。
108
+ 之后更新：`/plugin marketplace update agentbridge` 然后 `/reload-plugins`（或在 `/plugin` → **Marketplaces** → **agentbridge** 里启用自动更新）。
132
109
 
133
110
  ### 本地开发安装
134
111
 
135
112
  如需修改 AgentBridge 源码，使用本地开发模式：
136
113
 
137
114
  ```bash
138
- # 1. 克隆并安装依赖
139
115
  git clone https://github.com/raysonmeng/agent-bridge.git
140
116
  cd agent-bridge
141
117
  bun install
142
118
  bun link
143
119
 
144
- # 2. 安装本地插件 + 生成项目配置
145
120
  agentbridge dev # 注册本地 marketplace + 安装插件
146
121
  agentbridge init # 检查依赖、生成 .agentbridge/config.json
147
-
148
- # 3. 启动 Claude Code（自动加载 AgentBridge 插件）
149
- agentbridge claude
150
-
151
- # 4. 在另一个终端启动 Codex TUI 连接 Bridge
152
- agentbridge codex
122
+ agentbridge claude # 启动 Claude Code（自动加载插件）
123
+ agentbridge codex # （另一个终端）启动 Codex TUI 连接 Bridge
153
124
  ```
154
125
 
155
- > **注意：** `agentbridge claude` 会自动注入 `--dangerously-load-development-channels plugin:agentbridge@agentbridge`。这会把本地开发中的 channel 挂载进 Claude Code（当前属于 Research Preview）。请只启用你信任的 channel 和 MCP server。
156
-
157
- #### 修改代码后更新
158
-
159
- 修改 AgentBridge 源码后，重新执行 `agentbridge dev` 同步插件到缓存，然后重启 Claude Code 或在活跃会话中执行 `/reload-plugins`。
126
+ > **注意：** `agentbridge claude` 会注入 `--dangerously-load-development-channels plugin:agentbridge@agentbridge`（Research Preview 工作流）。请只启用你信任的 channel 和 MCP server。改完源码后，重新执行 `agentbridge dev` 并重启 Claude Code（或 `/reload-plugins`）。
160
127
 
161
128
  ## CLI 命令参考
162
129
 
@@ -166,16 +133,19 @@ agentbridge codex
166
133
  |------|------|
167
134
  | `abg init` | 安装插件、检查依赖（bun/claude/codex）、生成 `.agentbridge/config.json` |
168
135
  | `abg claude [args...]` | 启动 Claude Code 并启用 push channel。**默认带 `--dangerously-skip-permissions`**（关闭：`--safe` 或 `AGENTBRIDGE_SAFE=1`）。自动清除上次 `kill` 留下的 sentinel。额外参数透传给 `claude` |
169
- | `abg codex [args...]` | 启动连接 AgentBridge daemon 的 Codex TUI。**裸 `abg codex` 自动续接该对上次的 thread；`abg codex --new` 开新 thread。TUI 默认带 `--yolo`**（关闭：`--safe` 或 `AGENTBRIDGE_SAFE=1`；`exec` 等非 TUI 子命令不受影响）。管理 TUI 进程生命周期（pid 跟踪、清理）。额外参数透传给 `codex` |
136
+ | `abg codex [args...]` | 启动连接 AgentBridge daemon 的 Codex TUI。**裸 `abg codex` 自动续接该对上次的 thread；`abg codex --new` 开新 thread。TUI 默认带 `--yolo`**（关闭：`--safe` 或 `AGENTBRIDGE_SAFE=1`；`exec` 等非 TUI 子命令不受影响）。额外参数透传给 `codex` |
170
137
  | `abg resume [claude\|codex]` | 不带目标：打印本目录上次 Claude 会话 + 本对当前 Codex thread 的续接命令。带目标：直接续接该侧 |
171
- | `abg pairs` | 列出已注册的对；`abg pairs rm <name\|id>` 删除一个；`abg pairs prune` 预览可回收的孤儿目录 + 滞留 registry 条目（cwd 不存在/已死/>1 天），`abg pairs prune --apply` 执行删除 |
138
+ | `abg pairs` | 列出已注册的对；`abg pairs rm <name\|id>` 删除一个；`abg pairs prune` 预览可回收的孤儿目录 + 滞留 registry 条目，`--apply` 执行删除 |
172
139
  | `abg doctor [--json]` | 只读诊断：环境、daemon 健康/就绪、构建漂移、产物对齐、TUI 连接、日志 |
173
140
  | `abg budget [--json]` | 两侧订阅额度快照（5h/周窗口、漂移、暂停态） |
174
141
  | `abg logs [--codex] [-f] [-n N]` | tail 本对的 daemon 日志（或加 `--codex` tail Codex wrapper 日志）；`-f` 跟随，`-n N` 指定行数（默认 100） |
175
142
  | `abg kill` | 优雅停止本对 daemon 和托管的 Codex TUI，写入 killed sentinel；`abg kill --all` 停止所有对 |
176
143
  | `abg dev` | （开发用）注册本地 marketplace + 强制同步插件到缓存 |
177
- | `abg --help` | 显示帮助 |
178
- | `abg --version` | 显示版本 |
144
+ | `abg --help` / `abg --version` | 显示帮助 / 版本 |
145
+
146
+ ### 跨网协作 *(v3 预览)*
147
+
148
+ v3 协作层(跨机器/跨 agent 的共享房间,含 `auth` / `broker` / `room` / `join` / `publish` 命令)目前在 [`integration/v3-all`](https://github.com/quilin-ai/agent-bridge/tree/integration/v3-all) 分支预览,将随 v3 落地本分支。规格见 [docs/09-v3协作系统规格.md](docs/09-v3协作系统规格.md)。
179
149
 
180
150
  成对命令（`claude`、`codex`、`resume`、`kill`、`doctor`、`budget`、`logs`）接受 `--pair <name>` 指定具体的对——默认每个项目目录一对，端口按 +10 步长从 4500 分配。
181
151
 
@@ -189,12 +159,46 @@ agentbridge codex
189
159
 
190
160
  手动传入被拥有的参数会报错，并提示使用原生命令。
191
161
 
192
- > **关于 `agentbridge codex` 参数位置的说明：** 对于无子命令的 TUI 形式
193
- > （`agentbridge codex …`），bridge 注入的参数放在最前面。对于带有自己参数的
194
- > TUI 子命令（`resume`、`fork`），bridge 参数注入到**子命令名之后**（这样
195
- > clap 才会把它们解析为该子命令的选项，而不是根命令的）。`exec`、`mcp`、
196
- > `plugin`、`remote-control`、`update` 等非 TUI 子命令则原样透传，不注入
197
- > bridge 参数。完整定位逻辑见 `src/cli/codex.ts` 的 `buildCodexArgs`。
162
+ > **关于 `agentbridge codex` 参数位置：** 无子命令的 TUI 形式，bridge 参数注入到最前面；带自身参数的 TUI 子命令（`resume`、`fork`）注入到子命令名之后；`exec`、`mcp`、`plugin` 等非 TUI 子命令原样透传。完整逻辑见 `src/cli/codex.ts` 的 `buildCodexArgs`。
163
+
164
+ ## 架构
165
+
166
+ AgentBridge 是一个**两进程**本地 Bridge：
167
+
168
+ - **bridge.ts** —— 由 Claude Code 通过 AgentBridge 插件启动的前台 MCP 客户端，Claude Code 关闭时退出。
169
+ - **daemon.ts** —— 常驻本地后台进程，持有 Codex app-server 代理和桥接状态这一唯一真源。跨 Claude Code 重启存活；`bridge.ts` 以指数退避重连。
170
+
171
+ ```
172
+ ┌──────────────┐ MCP stdio / plugin ┌────────────────────┐
173
+ │ Claude Code │ ─────────────────────────▶ │ bridge.ts │
174
+ │ Session │ ◀───────────────────────── │ 前台 MCP 客户端 │
175
+ └──────────────┘ └─────────┬──────────┘
176
+ │
177
+ │ 控制 WS (:4502)
178
+ ▼
179
+ ┌────────────────────┐
180
+ │ daemon.ts │
181
+ │ 常驻后台桥接进程 │
182
+ └─────────┬──────────┘
183
+ │
184
+ ws://127.0.0.1:4501 proxy
185
+ │
186
+ ▼
187
+ ┌────────────────────┐
188
+ │ Codex app-server │
189
+ └────────────────────┘
190
+ ```
191
+
192
+ ### 数据流
193
+
194
+ | 方向 | 链路 |
195
+ |------|------|
196
+ | **Codex -> Claude** | `daemon.ts` 捕获 `agentMessage` -> 控制 WS -> `bridge.ts` -> `notifications/claude/channel` |
197
+ | **Claude -> Codex** | Claude 调用 `reply` tool -> `bridge.ts` -> 控制 WS -> `daemon.ts` -> `turn/start` 注入 Codex thread |
198
+
199
+ ### 防循环
200
+
201
+ 每条消息都携带 `source` 字段（`"claude"` 或 `"codex"`），Bridge 永远不会把消息转发回它的来源。
198
202
 
199
203
  ## 项目配置
200
204
 
@@ -206,56 +210,6 @@ agentbridge codex
206
210
 
207
211
  CLI 和 daemon 启动时会加载该配置。重复运行 `init` 是幂等的，不会覆盖已有文件。
208
212
 
209
- ## 文件结构
210
-
211
- ```
212
- agent_bridge/
213
- ├── .github/
214
- │ ├── ISSUE_TEMPLATE/ # Bug report 和 feature request 模板
215
- │ ├── pull_request_template.md
216
- │ └── workflows/ci.yml # GitHub Actions CI
217
- ├── assets/ # 图片资源
218
- ├── docs/ # 项目成长编年史（阶段 01-09，索引见 docs/README.md）
219
- │ ├── 01-起步与v1协作核心.md # 阶段 1：双向桥 + v1 协作核心
220
- │ ├── 02-Phase3产品化.md # 阶段 2：两进程架构 + CLI + 插件
221
- │ ├── …(03-08) # 发布 / 可靠性 / 多对 / 协作协议 v2 / 额度 / v2 架构愿景
222
- │ └── 09-v3协作系统规格.md # 阶段 9：最新 v3 跨网协作系统规格
223
- ├── plugins/agentbridge/ # Claude Code 插件包
224
- │ ├── .claude-plugin/plugin.json
225
- │ ├── commands/init.md
226
- │ ├── hooks/hooks.json
227
- │ ├── scripts/health-check.sh
228
- │ └── server/ # 打包的 bridge-server.js + daemon.js
229
- ├── src/
230
- │ ├── bridge.ts # Claude 前台 MCP 客户端（插件入口）
231
- │ ├── daemon.ts # 常驻后台 daemon
232
- │ ├── daemon-client.ts # daemon 控制端口的 WebSocket 客户端
233
- │ ├── daemon-lifecycle.ts # 共享 daemon 生命周期（ensureRunning、kill、启动锁）
234
- │ ├── control-protocol.ts # 前后台控制协议类型
235
- │ ├── claude-adapter.ts # Claude Code channel 的 MCP server 适配层
236
- │ ├── codex-adapter.ts # Codex app-server WebSocket 代理与消息拦截
237
- │ ├── config-service.ts # 项目配置（.agentbridge/）读写
238
- │ ├── state-dir.ts # 平台感知的状态目录解析
239
- │ ├── message-filter.ts # 智能消息过滤（标记、摘要缓冲）
240
- │ ├── types.ts # 共享类型
241
- │ ├── cli.ts # CLI 入口和命令路由
242
- │ └── cli/
243
- │ ├── init.ts # agentbridge init
244
- │ ├── claude.ts # agentbridge claude
245
- │ ├── codex.ts # agentbridge codex
246
- │ ├── kill.ts # agentbridge kill
247
- │ └── dev.ts # agentbridge dev
248
- ├── CLAUDE.md # AI Agent 项目规则
249
- ├── CODE_OF_CONDUCT.md
250
- ├── CONTRIBUTING.md
251
- ├── LICENSE
252
- ├── README.md
253
- ├── README.zh-CN.md
254
- ├── SECURITY.md
255
- ├── package.json
256
- └── tsconfig.json
257
- ```
258
-
259
213
  ## 配置
260
214
 
261
215
  ### 环境变量
@@ -277,15 +231,7 @@ agent_bridge/
277
231
 
278
232
  ### 更新提示
279
233
 
280
- `abg claude` 和 `abg codex` 在 npm 上有更新的**稳定**版本时,会向 stderr 打印一行提示,例如:
281
-
282
- ```
283
- ⚠ AgentBridge update available: 0.1.6 → 0.1.7
284
- CLI: npm install -g @raysonmeng/agentbridge@latest
285
- Plugin: /plugin marketplace update agentbridge (then /reload-plugins)
286
- ```
287
-
288
- 该检查是 best-effort：提示从缓存打印，npm 检查每天最多在后台跑一次，任何网络/registry 失败都静默忽略。交互式 TTY 下，命中缓存更新会在启动前询问；输入 `y` 会运行 `npm install -g @raysonmeng/agentbridge@latest`，输入 `N`（或 15 秒内无应答）会记住本版本已拒绝并继续启动。非交互(管道)输出和 CI 下绝不询问，可用 `NO_UPDATE_NOTIFIER=1` 关闭提示，或用 `AGENTBRIDGE_UPDATE_PROMPT=0` 保持纯打印。
234
+ `abg claude` 和 `abg codex` 在 npm 上有更新的**稳定**版本时，会向 stderr 打印一行提示。该检查是 best-effort：从缓存打印，npm 检查每天最多在后台跑一次，任何网络/registry 失败都静默忽略。交互式 TTY 下，命中缓存更新会在启动前询问；输入 `y` 执行升级，`N`（或 15 秒内无应答）记住本版本已拒绝并继续。可用 `NO_UPDATE_NOTIFIER=1` 关闭，或用 `AGENTBRIDGE_UPDATE_PROMPT=0` 保持纯打印。
289
235
 
290
236
  ### 状态目录
291
237
 
@@ -298,58 +244,41 @@ daemon 在平台感知的目录中存储运行时状态：
298
244
 
299
245
  内容：`daemon.pid`、`status.json`、`agentbridge.log`、`killed`（sentinel）、`startup.lock`
300
246
 
301
- ### Bridge 禁用状态
302
-
303
- Bridge 在无法接受新 MCP 回复时会进入若干休眠状态。每种状态都会以错误信息返回给 agent；瞬态状态还会推送一条带内通知：
304
-
305
- | 状态 | 原因 | 恢复方式 |
306
- |------|------|---------|
307
- | `killed` | 运行过 `agentbridge kill`，存在 sentinel 文件。 | 重启 Claude Code（`agentbridge claude`），切换到新会话，或运行 `/resume`。 |
308
- | `rejected` | daemon 拒绝连接：已有另一个 Claude 会话连接中。 | 先关闭另一个会话，或运行 `agentbridge kill` 重置，然后重新 `agentbridge claude`。 |
309
- | `evicted` | 在位会话未响应存活探测，被更新的会话驱逐（issue #68）。 | 关闭本会话，用 `agentbridge claude` 重新启动一个。 |
310
- | `probe_in_progress` | 当前正在对在位会话执行存活探测——争用窗口期。瞬态（在 `DISABLED_RECOVERY_INTERVAL_MS` × 重试上限内自动恢复，约 30 秒）。 | 无需操作；恢复轮询会在槽位释放后自动重连。 |
311
- | `auto_recovery_exhausted` | `probe_in_progress` 的自动恢复轮询用尽了完整的重试预算（6 次，约 30 秒）仍未成功。终态。 | 手动用 `agentbridge claude` 重试。 |
312
-
313
247
  ## 额度协调与自动续接
314
248
 
315
- AgentBridge 能让长任务跨订阅额度窗口持续推进，而不是某一侧撞到上限就中断。这套能力由配套的 **agent-quota-guard** 工具驱动：bridge 读它的额度探针和 `pending` 记录——装上 guard 才会启用。
316
-
317
- daemon 里的额度协调器轮询**两侧**账号级 5h/周额度（经 guard 的探针）并协调两边；`abg budget [--json]` 打印实时快照（两个窗口、漂移、暂停态）。装上 guard 后再激活两项能力：
318
-
319
- - **减速线——中途不腰斩。** 接近额度硬线时，guard **不**在工具调用中途 deny，而是给一条提醒、让当前 turn 跑完，在**回合边界干净停下**，写 `.agent/checkpoint.md`，并落一条 bridge 能检测的 `pending` 记录。
320
- - **窗口刷新后全自动续接。** 当被暂停一侧的额度窗口刷新，bridge 在**原本的交互式 TUI** 里续接任务——不开后台无头进程、不需手动：
321
- - **Codex**：排队的 `turn/start` 注入（`ResumeInjectionQueue`）开一个新 turn，从 checkpoint 接着干。全自动。
322
- - **Claude**：channel push 一条带稳定 `resume_id` 的指令；Claude 经 `ack_resume` MCP tool 回执。未回执则用新 delivery id 重推（`resume_id` 不变）；重试耗尽后落 `SessionStart` 降级 sentinel，下个会话读到恢复提示。
323
- - **幂等**：每条 pending 一个 claim/consumed 墓碑（agent+session+cwd+内容哈希 的 sha256），保证同一续接最多注入一次，跨 daemon 重启亦然；陈旧墓碑按 TTL 清理。
249
+ AgentBridge 能让长任务跨订阅额度窗口持续推进，而不是某一侧撞到上限就中断。这套能力由配套工具 **[agent-quota-guard](https://www.npmjs.com/package/agent-quota-guard)**（[repo](https://github.com/raysonmeng/agent-quota-guard) · v0.2.0，2026-06-13）驱动——装上 guard 才启用。
324
250
 
325
- 任务运行中 bridge 可能发的协调指令：**balance**（把更多活分给 runway 更长 / 剩余可工作时间更多的一侧）、**underutilized**（账号周额度在刷新前烧不满时——多拆并行子任务 / 提高委派密度）、**pause / handoff / resume**。
251
+ - **快照** —— daemon 经 guard 的探针轮询两侧账号级 5h/周额度；`abg budget [--json]` 打印实时快照（两个窗口、漂移、暂停态）。只要装了 guard 的探针就能用。
252
+ - **减速线（中途不腰斩）** —— 接近额度硬线时，guard **不**在工具调用中途 deny，而是让当前 turn 跑完、在回合边界干净停下、写 `.agent/checkpoint.md`，并落一条 bridge 能检测的 `pending` 记录。
253
+ - **全自动续接** —— 被暂停一侧窗口刷新后，bridge 在**原本的交互式 TUI** 里续接：Codex 经排队的 `turn/start` 注入，Claude 经 channel push 并由 `ack_resume` 回执。每条 pending 的幂等墓碑保证同一续接最多注入一次，跨 daemon 重启亦然。
326
254
 
327
- > 减速线 + 自动续接是可选的、依赖配套 guard 的能力。Claude 侧续接是 best-effort（ack + 重试 + SessionStart 兜底）：对完全空闲会话的 channel push 存在已知的上游不确定性，故 bridge 只有看到真正的 `ack_resume` 才标记该侧已续接。
255
+ > **实验性 / opt-in。** 这是依赖配套 guard 的能力。Claude 侧续接是 best-effort（ack + 重试 + `SessionStart` 兜底）：对完全空闲会话的 channel push 存在已知上游不确定性，故 bridge 只有看到真正的 `ack_resume` 才标记该侧已续接。
328
256
 
329
257
  ## 当前限制
330
258
 
331
259
  - 目前只转发 `agentMessage`，不转发 `commandExecution`、`fileChange` 等中间过程事件
332
260
  - 每对只有单个 Codex thread，对内暂不支持多会话
333
261
  - 每对只有单个 Claude 前台连接；新的 Claude 会话会替换旧连接
334
- - 多对可在同机并行（每个项目目录一对、按对分配端口）；Windows 暂非官方支持平台
262
+ - 多对可在同机并行（每个项目目录一对）；Windows 暂非官方支持平台
335
263
 
336
- ### Codex 的 Git 操作限制
264
+ 休眠/禁用状态、Codex `.git` 限制及其它坑，见 **[排错文档](docs/TROUBLESHOOTING.md)**。
337
265
 
338
- Codex 运行在沙箱环境中，**禁止对 `.git` 目录进行任何写操作**。这意味着 Codex 无法执行 `git commit`、`git push`、`git pull`、`git checkout -b`、`git merge` 等任何修改 Git 元数据的命令。尝试执行这些命令会导致 Codex 会话无限期挂起。
266
+ ## Roadmap
339
267
 
340
- **建议做法：** 让 Claude Code 负责所有 Git 操作（创建分支、提交、推送、创建 PR）。Codex 专注于代码修改，通过 `agentMessage` 汇报完成的工作，由 Claude Code 负责 Git 工作流。
268
+ - **更多 adapter** —— 今天 AgentBridge 接的是 Claude Code ↔ Codex。下一个候选：**OpenCode、OpenClaw、Hermes Agent、Gemini CLI**。到 [adapter roadmap issue](https://github.com/quilin-ai/agent-bridge/issues/212) 投票。
269
+ - **能力网格（Capability mesh）** —— 超越消息传递：连上的 agent 会发布自己的命令 / skills / MCP tools，让对等体直接调用——从「传消息」走向「调能力」。
270
+ - **v2 —— 多 Agent 基础设施**（部分已落地）：Room 作用域协作、稳定身份、正式控制协议、更强恢复。见 [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md)。
271
+ - **v3 —— 跨网协作**（preview，见上面的实验性 CLI）：跨机器、跨 agent 的共享房间，经 broker。见 [docs/09-v3协作系统规格.md](docs/09-v3协作系统规格.md)。
341
272
 
342
- ## Roadmap
273
+ ## 文档
343
274
 
344
- - **v1.x（当前）**：在不改变架构的前提下优化单桥体验 -- 降噪、控回合、定角色。详见 [docs/01-起步与v1协作核心.md](docs/01-起步与v1协作核心.md)。
345
- - **v2（规划中）**：引入多 Agent 基础设施 -- Room 作用域协作、稳定身份、正式控制协议、更强的恢复语义。详见 [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md)。
346
- - **v3+（远期）**：更智能的协作、更丰富的策略、跨 runtime 的高级编排。
275
+ - **[排错 / Troubleshooting](docs/TROUBLESHOOTING.md)** —— 禁用状态恢复、Codex `.git` 挂死、「装了却跑不起来」、Bun 版本要求
276
+ - **[使用手册](https://github.com/quilin-ai/agent-bridge/blob/integration/v3-all/docs/manual/使用手册.md)**（[English](https://github.com/quilin-ai/agent-bridge/blob/integration/v3-all/docs/manual/manual-en.md)）—— 端到端使用走查
277
+ - **[项目成长编年史](docs/README.md)** —— AgentBridge 是怎么一步步长起来的（阶段 01–11）
347
278
 
348
279
  ## 这个项目是怎么建成的
349
280
 
350
- 这个项目由 **Claude Code**（Anthropic）和 **Codex**（OpenAI）通过 AgentBridge 本身进行实时双向通信，在人类开发者的指挥下协作完成。开发者负责分配任务、审查进度，并指挥两个 Agent 并行工作、互相 review。
351
-
352
- 换句话说，AgentBridge 就是它自己的 proof of concept：两个来自不同厂商的 AI Agent，通过实时连接，肩并肩地交付代码。
281
+ 这个项目由 **Claude Code**（Anthropic）和 **Codex**（OpenAI）通过 AgentBridge 本身进行实时双向通信，在人类开发者的指挥下协作完成。开发者负责分配任务、审查进度，并指挥两个 Agent 并行工作、互相 review。换句话说，AgentBridge 就是它自己的 proof of concept：两个来自不同厂商的 AI Agent，通过实时连接，肩并肩地交付代码。
353
282
 
354
283
  ## 联系方式
355
284
 
package/dist/cli.js CHANGED
@@ -179,7 +179,7 @@ function parsePositiveIntEnv(name, fallback, log = () => {}, env = process.env)
179
179
  var require_package = __commonJS((exports, module) => {
180
180
  module.exports = {
181
181
  name: "@raysonmeng/agentbridge",
182
- version: "0.1.24",
182
+ version: "0.1.26",
183
183
  description: "Bridge between Claude Code and Codex \u2014 bidirectional agent communication via MCP Channel + JSON-RPC",
184
184
  type: "module",
185
185
  packageManager: "bun@1.3.11",
@@ -1708,11 +1708,11 @@ function formatBuildInfo(build) {
1708
1708
  var CODE_HASH_SENTINEL = "source", BUILD_INFO;
1709
1709
  var init_build_info = __esm(() => {
1710
1710
  BUILD_INFO = Object.freeze({
1711
- version: defineString("0.1.24", "0.0.0-source"),
1712
- commit: defineString("39a46f1", "source"),
1711
+ version: defineString("0.1.26", "0.0.0-source"),
1712
+ commit: defineString("f53e48c", "source"),
1713
1713
  bundle: defineBundle("dist"),
1714
1714
  contractVersion: defineNumber(1, CONTRACT_VERSION),
1715
- codeHash: defineString("aeb64ca4c8b6", "source")
1715
+ codeHash: defineString("e7a1d151eaf5", "source")
1716
1716
  });
1717
1717
  });
1718
1718
 
package/dist/daemon.js CHANGED
@@ -29,11 +29,11 @@ function defineNumber(value, fallback) {
29
29
  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
30
30
  }
31
31
  var BUILD_INFO = Object.freeze({
32
- version: defineString("0.1.24", "0.0.0-source"),
33
- commit: defineString("39a46f1", "source"),
32
+ version: defineString("0.1.26", "0.0.0-source"),
33
+ commit: defineString("f53e48c", "source"),
34
34
  bundle: defineBundle("dist"),
35
35
  contractVersion: defineNumber(1, CONTRACT_VERSION),
36
- codeHash: defineString("aeb64ca4c8b6", "source")
36
+ codeHash: defineString("e7a1d151eaf5", "source")
37
37
  });
38
38
  function daemonStatusBuildInfo() {
39
39
  return { ...BUILD_INFO };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@raysonmeng/agentbridge",
3
- "version": "0.1.24",
3
+ "version": "0.1.26",
4
4
  "description": "Bridge between Claude Code and Codex — bidirectional agent communication via MCP Channel + JSON-RPC",
5
5
  "type": "module",
6
6
  "packageManager": "bun@1.3.11",
package/plugins/agentbridge/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentbridge",
3
- "version": "0.1.24",
3
+ "version": "0.1.26",
4
4
  "description": "Bridge Claude Code and Codex with a shared daemon, push channel delivery, and bidirectional reply tooling.",
5
5
  "author": {
6
6
  "name": "AgentBridge Contributors",
package/plugins/agentbridge/server/bridge-server.js CHANGED
@@ -14706,11 +14706,11 @@ function defineNumber(value, fallback) {
14706
14706
  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
14707
14707
  }
14708
14708
  var BUILD_INFO = Object.freeze({
14709
- version: defineString("0.1.24", "0.0.0-source"),
14710
- commit: defineString("39a46f1", "source"),
14709
+ version: defineString("0.1.26", "0.0.0-source"),
14710
+ commit: defineString("f53e48c", "source"),
14711
14711
  bundle: defineBundle("plugin"),
14712
14712
  contractVersion: defineNumber(1, CONTRACT_VERSION),
14713
- codeHash: defineString("aeb64ca4c8b6", "source")
14713
+ codeHash: defineString("e7a1d151eaf5", "source")
14714
14714
  });
14715
14715
  function sameRuntimeContract(a, b) {
14716
14716
  if (!a || !b)
package/plugins/agentbridge/server/daemon.js CHANGED
@@ -29,11 +29,11 @@ function defineNumber(value, fallback) {
29
29
  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
30
30
  }
31
31
  var BUILD_INFO = Object.freeze({
32
- version: defineString("0.1.24", "0.0.0-source"),
33
- commit: defineString("39a46f1", "source"),
32
+ version: defineString("0.1.26", "0.0.0-source"),
33
+ commit: defineString("f53e48c", "source"),
34
34
  bundle: defineBundle("plugin"),
35
35
  contractVersion: defineNumber(1, CONTRACT_VERSION),
36
- codeHash: defineString("aeb64ca4c8b6", "source")
36
+ codeHash: defineString("e7a1d151eaf5", "source")
37
37
  });
38
38
  function daemonStatusBuildInfo() {
39
39
  return { ...BUILD_INFO };