npm - @raysonmeng/agentbridge - Versions diffs - 0.1.30 → 0.1.31 - Mend

@raysonmeng/agentbridge 0.1.30 → 0.1.31

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 (13) hide show

package/.claude-plugin/marketplace.json +1 -1
package/README.md +51 -28
package/README.zh-CN.md +60 -37
package/dist/cli.js +2914 -138
package/dist/daemon.js +1692 -271
package/package.json +1 -1
package/plugins/agentbridge/.claude-plugin/plugin.json +1 -1
package/plugins/agentbridge/hooks/hooks.json +12 -1
package/plugins/agentbridge/scripts/publish-completion.sh +34 -0
package/plugins/agentbridge/server/bridge-server.js +208 -12
package/plugins/agentbridge/server/daemon.js +1692 -271
package/scripts/install-safety.cjs +2 -1
package/scripts/postinstall.cjs +1 -1

package/.claude-plugin/marketplace.json CHANGED Viewed

@@ -12,7 +12,7 @@
     {
       "name": "agentbridge",
       "description": "Bridge Claude Code and Codex through a shared daemon, push channel delivery, and reply/get_messages tools.",
-      "version": "0.1.30",
+      "version": "0.1.31",
       "author": {
         "name": "AgentBridge Contributors",
         "email": "raysonmeng@qq.com"

package/README.md CHANGED Viewed

@@ -7,27 +7,34 @@
 [中文文档](README.zh-CN.md)
-**🌐 Website: [quilin-ai.github.io/agent-bridge](https://quilin-ai.github.io/agent-bridge/)** — with a live animated demo of a real session.
+**🌐 Website: [raysonmeng.github.io/agent-bridge](https://raysonmeng.github.io/agent-bridge/)**, with an animated replay of a real session.
+> Discussed on [LINUX DO](https://linux.do) — the developer community. / 在 [LINUX DO](https://linux.do) 开发者社区交流。
 Local bridge for bidirectional communication between Claude Code and Codex inside the same working session.
+<p align="center">
+  <img src="assets/readme-demo.gif" width="820" alt="Claude Code and Codex reviewing each other in one live session" />
+  <br />
+  <sub>A real session, replayed — Codex's review is pushed into Claude's live session, no human relay. <a href="https://raysonmeng.github.io/agent-bridge/">Full animated demo →</a></sub>
+</p>
 What that buys you, concretely:
-- **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.
+- **Cross-review** — Codex implements; Claude reviews the diff *inside the same session* and pushes change requests straight back into Codex's thread. Two providers check each other's work without copy-paste.
 - **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.
 - **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.
-<!-- TODO: assets/demo.gif — see docs/demo/RECORDING.md -->
-▶ **[Watch the demo on the website](https://quilin-ai.github.io/agent-bridge/)** — an animated replay of a real session: Codex's reply pushed into Claude's live session, a mid-turn injection into Codex, and a quota handoff.
 > **This tool was largely built by Claude Code and Codex collaborating through it.**
 > **Every PR written by one agent was reviewed by the other.** AgentBridge is its own proof of concept.
+> ⭐ If AgentBridge is useful to you, a star helps other people running two agents find it.
 ## Why not just…
-- **…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.
-- **…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.
-- **…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.
+- **…run two terminals and copy-paste?** You can, but then you are the message bus: you ferry text by hand and guess when it is safe to interrupt. AgentBridge automates the relay: messages flow on their own, a busy-guard blocks replies during an active turn, and the bridge filters noisy intermediate events so each side sees only the other's meaningful output.
+- **…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.
+- **…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.
 ## What this project is / is not
@@ -45,7 +52,7 @@ What that buys you, concretely:
 ## Features
-- **Bidirectional Claude ↔ Codex messaging** in one working session — Codex output is intercepted and pushed to Claude as channel notifications; Claude replies via the `reply` MCP tool, injected into the Codex thread as a `turn/start`.
+- **Bidirectional Claude ↔ Codex messaging** in one working session — the daemon intercepts Codex output and pushes it to Claude as channel notifications; Claude replies via the `reply` MCP tool, and the bridge injects the reply into the Codex thread as a `turn/start`.
 - **Push delivery with fallback** — messages arrive as channel notifications; a failed push falls back to an in-memory queue drained by `get_messages`. Loop prevention via the per-message `source` field.
 - **Turn coordination** — a busy-guard rejects replies during an active Codex turn; a per-turn inactivity watchdog stops a lost `turn/completed` from locking injection forever; noisy intermediate events are collapsed so only meaningful `agentMessage` payloads reach Claude.
 - **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`.
@@ -53,39 +60,54 @@ What that buys you, concretely:
 - **Thread auto-resume** — bare `abg codex` resumes the pair's last Codex thread; `abg resume` prints/performs the resume commands for both sides.
 - **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).
+## Context handling — real-time, without the context blowing up
+A common worry about real-time bidirectional messaging is that the two agents' contexts merge and grow without bound. They don't. **The bridge passes messages, not context** — each agent keeps its own context window, and the bridge never copies one agent's full transcript into the other. (And which agent plans vs executes is your call — the roles aren't fixed; Codex can drive Claude just as easily.) Three filters keep what actually crosses small:
+1. **Only `agentMessage` crosses.** The bridge forwards an agent's actual conclusions, not its tool-call noise — `commandExecution`, `fileChange`, and reasoning deltas never reach the other side, nor does its full scrollback.
+2. **Three-tier marker routing** (default `filtered` mode). Each message is tagged and the daemon routes by tag: `[IMPORTANT]` forwards immediately, `[STATUS]` is buffered and batched into one periodic summary (default: 3 updates or 15s), `[FYI]` is dropped. The marker rules live once in the project's `AGENTS.md` (written by `abg init`), loaded at agent startup.
+3. **The collaboration contract lives once** in `AGENTS.md`, not appended to every message (which would pollute every thread and its resume title).
+Net effect: each side receives a curated stream of meaningful messages, so context grows with the number of real exchanges — not the other agent's raw activity. Set `AGENTBRIDGE_FILTER_MODE=full` (or the config equivalent) when you *do* want the unfiltered stream.
 ## Prerequisites
-| Dependency | Version | Install |
+| Dependency | Recommended version | Install |
 |-----------|---------|---------|
 | [Bun](https://bun.sh) | v1.3.11+ | `curl -fsSL https://bun.sh/install \| bash` |
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | v2.1.80+ | `npm install -g @anthropic-ai/claude-code` |
-| [Codex CLI](https://github.com/openai/codex) | latest | `npm install -g @openai/codex` |
+| [Claude Code](https://code.claude.com/docs/en/quickstart) | 2.1.269 | `npm install -g @anthropic-ai/claude-code@2.1.269` |
+| [Codex CLI](https://developers.openai.com/codex/cli) | 0.154.0 | `npm install -g @openai/codex@0.154.0` |
-> **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)).
+Claude Code and Codex recommendations are the publishers' latest stable npm versions checked on 2026-09-12. These recommendations do not change the existing minimum-version checks. Cross-machine Codex messaging, acknowledgements and daemon/session recovery were also verified with Codex 0.153.4. For room setup and the one-time `--new` step after upgrading, see [Codex remote rooms](docs/CODEX-ROOMS.md).
+> **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, install Bun first (see [Troubleshooting](docs/TROUBLESHOOTING.md)).
 ## Quick Start
-Four steps from nothing to a running pair:
+Five steps from nothing to a running pair:
 ```bash
-# 1. Install Bun (the runtime — Node alone won't work)
+# 1. Install Bun (the runtime; Node alone won't work)
 curl -fsSL https://bun.sh/install | bash
 # 2. Install the CLI. postinstall auto-registers the Claude Code plugin
 #    marketplace AND installs the plugin (best-effort; needs bun + claude present).
 npm install -g @raysonmeng/agentbridge
-# 3. Start Claude Code with the AgentBridge channel enabled
+# 3. Initialize the project (check deps, install plugin if needed, write .agentbridge/config.json)
+abg init
+# 4. Start Claude Code with the AgentBridge channel enabled
 abg claude
-# 4. In another terminal, start Codex TUI connected to the same bridge
+# 5. In another terminal, start Codex TUI connected to the same bridge
 abg codex
 ```
-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).
+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).
 > [!WARNING]
-> **`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.
+> **`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. 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.
 ### Your first collaboration
@@ -93,7 +115,7 @@ With both sides running, give Claude a task that wants a second agent, e.g.:
 > **Ask Claude:** *"Propose a task split with Codex for &lt;your task&gt;, then have Codex implement its part while you review."*
-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.
+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, without you relaying anything by hand.
 ### Manual plugin install (fallback)
@@ -150,9 +172,9 @@ agentbridge codex   # (another terminal) Start Codex TUI connected to the bridge
 ### Cross-network collaboration *(v3 preview)*
-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).
+The v3 collaboration layer ships in **0.1.31**: shared rooms across machines over a broker, with `auth`, `broker`, `room`, `join` and `publish` commands. Codex-only machines can use native room tools to exchange messages and acknowledgements. See [Codex remote rooms](docs/CODEX-ROOMS.md) for setup and delivery limits, and the [user manual](docs/manual/manual-en.md) for broker and membership administration.
-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.
+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.
 ### Owned flags
@@ -251,7 +273,7 @@ Contents: `daemon.pid`, `status.json`, `agentbridge.log`, `killed` (sentinel), `
 ## Budget Coordination & Auto-Resume
-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.
+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.
 - **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.
 - **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.
@@ -270,25 +292,26 @@ For dormant/disabled bridge states, the Codex `.git` restriction, and other gotc
 ## Roadmap
-- **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).
-- **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*.
+- **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/raysonmeng/agent-bridge/issues/212).
+- **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.
 - **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).
-- **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).
+- **v3 — cross-network collaboration** (included in 0.1.31, experimental): shared rooms across machines and agents over a broker. See [Codex remote rooms](docs/CODEX-ROOMS.md).
 ## Docs
 - **[Troubleshooting](docs/TROUBLESHOOTING.md)** — disabled-state recovery, the Codex `.git` hang, "installed but won't run", Bun version requirements
-- **[User manual (EN)](https://github.com/quilin-ai/agent-bridge/blob/integration/v3-all/docs/manual/manual-en.md)** — end-to-end usage walkthrough
+- **[User manual (EN)](docs/manual/manual-en.md)** — end-to-end usage walkthrough
 - **[Project growth timeline](docs/README.md)** — how AgentBridge was built, stage by stage (01–11)
 ## How This Project Was Built
-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.
+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.
 ## Contact
 This is my first open-source project! I'd love to connect with anyone interested in multi-agent collaboration, AI tooling, or just building cool things together. Feel free to reach out:
+- **Website**: [raysonmeng.pages.dev](https://raysonmeng.pages.dev/)
 - **Twitter/X**: [@raysonmeng](https://x.com/raysonmeng)
 - **Xiaohongshu**: [Profile](https://www.xiaohongshu.com/user/profile/62a3709d0000000021028b7e)
 - **WeChat**: Scan the QR code below to add me

package/README.zh-CN.md CHANGED Viewed

@@ -7,27 +7,34 @@ English version: [README.md](README.md)
 [![CI](https://github.com/raysonmeng/agent-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/raysonmeng/agent-bridge/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-**🌐 官网：[quilin-ai.github.io/agent-bridge/zh/](https://quilin-ai.github.io/agent-bridge/zh/)** —— 附真实会话的动画演示。
+**🌐 官网：[raysonmeng.github.io/agent-bridge/zh/](https://raysonmeng.github.io/agent-bridge/zh/)**，附真实会话的动画重放。
+> 在 [LINUX DO](https://linux.do) 开发者社区交流讨论。
 让 Claude Code 和 Codex 在同一个工作会话中进行双向通信的本地 Bridge。
-具体能换来什么：
+<p align="center">
+  <img src="assets/readme-demo.gif" width="820" alt="Claude Code 和 Codex 在同一个会话里互相 review" />
+  <br />
+  <sub>真实会话重放 —— Codex 的 review 被直接推进 Claude 的活跃会话，全程没有人肉搬运。<a href="https://raysonmeng.github.io/agent-bridge/zh/">完整动画演示 →</a></sub>
+</p>
-- **不只是互相说话，是互相 review** —— Codex 写实现，Claude 在**同一会话内**实时 review 这个 diff，并把修改意见直接推回 Codex 的 thread。两家模型互相盯着对方，不用复制粘贴。
-- **一句 prompt 完成分工** —— 让任一侧提出与对方的分工方案，两个 agent 先商量好谁做什么再动手写代码。你把舵，它们协调。
-- **通宵任务的额度接力** —— 一侧订阅额度窗口烧到线时，它在回合边界干净停下，把任务交接给另一侧，让长任务继续跑,而不是撞到上限就死掉。
+具体能换来什么：
-<!-- TODO: assets/demo.gif — see docs/demo/RECORDING.md -->
-▶ **[在官网看演示](https://quilin-ai.github.io/agent-bridge/zh/)** —— 真实会话的动画重放：Codex 回复推进 Claude 活跃会话、回合中途插入、额度接力。
+- **交叉 review**：Codex 写实现，Claude 在**同一会话内**实时 review 这个 diff，并把修改意见直接推回 Codex 的 thread。两家模型互相盯着对方，不用复制粘贴。
+- **一句 prompt 完成分工**：让任一侧提出与对方的分工方案，两个 agent 先商量好谁做什么再动手写代码。你把舵，它们协调。
+- **通宵任务的额度接力**：一侧订阅额度窗口烧到线时，它在回合边界干净停下，把任务交接给另一侧，让长任务继续跑。
 > **这个工具很大程度上就是 Claude Code 和 Codex 通过它本身协作写出来的。**
 > **一个 agent 写的每个 PR,都由另一个 agent review。** AgentBridge 就是它自己的 proof of concept。
+> ⭐ 如果 AgentBridge 对你有用，点个 star 能帮到其他双开的人找到它。
 ## Why not just…（换个方案不行吗)
-- **……开两个终端手动复制粘贴?** 可以——但你就成了消息总线,手动搬运文本、靠肉眼判断什么时候能插话。AgentBridge 把这套中转自动化了:消息自己流动,busy-guard 在活跃 turn 期间挡住回复,噪声中间事件被过滤,每一侧只看到对方有意义的输出。
-- **……用一个单向委派插件?** 像 `openai/codex-plugin-cc` 这类工具,是宿主**调用** Codex、拿回一个答案——问进去、答出来,对面没有一个常驻的对等体。AgentBridge 让**两个** agent 都作为常驻对等体活着,任一侧都能在**回合中途**推消息(review 意见在对方还在干活时就落进它会话),而不只是在调用边界。
-- **……接一个外部编排器?** 一个上帝进程调度哑终端是自上而下的:一个大脑、N 个互不说话的 worker。AgentBridge 是对等的——两个完整 agent 在会话内对话、自己提分工、互相 review,人在旁边把舵,而不是脚本化每一跳。
+- **……开两个终端手动复制粘贴?** 可以，但你就成了消息总线：手动搬运文本，靠肉眼判断什么时候能插话。AgentBridge 把这套中转自动化了:消息自己流动,busy-guard 在活跃 turn 期间挡住回复,噪声中间事件被过滤,每一侧只看到对方有意义的输出。
+- **……用一个单向委派插件?** 像 `openai/codex-plugin-cc` 这类工具,是宿主**调用** Codex、拿回一个答案：问进去、答出来，对面没有常驻的对等体。AgentBridge 让**两个** agent 都作为常驻对等体活着,任一侧都能在**回合中途**推消息(review 意见在对方还在干活时就落进它会话),而不只是在调用边界。
+- **……接一个外部编排器?** 一个上帝进程调度哑终端是自上而下的:一个大脑、N 个互不说话的 worker。AgentBridge 是对等的：两个完整 agent 在会话内对话、自己提分工、互相 review,人在旁边把舵,而不是脚本化每一跳。
 ## 这个项目是什么 / 不是什么
@@ -53,39 +60,54 @@ English version: [README.md](README.md)
 - **Thread 自动续接**：裸 `abg codex` 续接该对上次的 Codex thread；`abg resume` 打印/执行两侧的续接命令。
 - **额度协调、减速线与全自动续接**：让长任务跨订阅额度窗口持续推进，而不是撞到上限就中断。见 [额度协调与自动续接](#额度协调与自动续接)。
+## 上下文处理 —— 实时双向，但上下文不会爆
+很多人对"实时双向通信"最大的担心是：两个 agent 的上下文会不会合并、越滚越大。不会。**桥传的是消息，不是上下文** —— 每个 agent 各自维护自己的上下文窗口，桥从不会把一方的完整对话历史拷进另一方。（而且谁规划、谁执行完全由你定，角色不写死，让 Codex 指挥 Claude 也一样。）在这个前提上，三层过滤让真正跨过桥的东西尽量少：
+1. **只转发 `agentMessage`。** 桥只转发 agent 真正说出来的结论，它执行命令的输出、`commandExecution`、`fileChange`、推理过程这些中间噪声和完整 scrollback 都不过桥。每一方看到的是对方的结论，不是干活的流水账。
+2. **三级标签路由**（默认 `filtered` 模式）。每条消息带标签，daemon 按标签决定去留：`[IMPORTANT]` 立刻转发，`[STATUS]` 先缓冲、攒几条（默认 3 条或 15 秒）合并成一条摘要，`[FYI]` 直接丢。标签规则一次性写在项目的 `AGENTS.md` 里（`abg init` 注入），agent 启动读一次。
+3. **协作契约只存一份**在 `AGENTS.md`，不附带在每条消息上（否则每个 thread 和它的 resume 标题都会被污染）。
+最终效果：每一方收到的是对方精选过的有意义消息，上下文的增长跟的是"有效交流的条数"，不是"对方活动的原始量"。需要看完整原文时，设 `AGENTBRIDGE_FILTER_MODE=full` 即可关掉过滤。
 ## 前置条件
-| 依赖 | 版本 | 安装方式 |
+| 依赖 | 推荐版本 | 安装方式 |
 |------|------|----------|
 | [Bun](https://bun.sh) | v1.3.11+ | `curl -fsSL https://bun.sh/install \| bash` |
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | v2.1.80+ | `npm install -g @anthropic-ai/claude-code` |
-| [Codex CLI](https://github.com/openai/codex) | latest | `npm install -g @openai/codex` |
+| [Claude Code](https://code.claude.com/docs/en/quickstart) | 2.1.269 | `npm install -g @anthropic-ai/claude-code@2.1.269` |
+| [Codex CLI](https://developers.openai.com/codex/cli) | 0.154.0 | `npm install -g @openai/codex@0.154.0` |
-> **Bun 是必要运行时**（AgentBridge daemon 和插件服务器都跑在 Bun 上），仅有 Node.js 不够——如果 `abg` 装上了却跑不起来，八成就是缺 Bun（见 [排错](docs/TROUBLESHOOTING.md)）。
+以上 Claude Code、Codex 推荐值来自发布方 npm 的最新稳定版，核对日期为 2026-09-12；不改变现有最低版本检查。Codex 0.153.4 也已通过双机消息、ACK 和 daemon/会话恢复验证。房间配置及升级后首次使用 `--new` 的说明见 [Codex 跨机房间](docs/CODEX-ROOMS.md)。
+> **Bun 是必要运行时**（AgentBridge daemon 和插件服务器都跑在 Bun 上），仅有 Node.js 不够。如果 `abg` 装上了却跑不起来，八成就是缺 Bun（见 [排错](docs/TROUBLESHOOTING.md)）。
 ## Quick Start
-从零到一对跑起来，四步：
+从零到一对跑起来，五步：
 ```bash
-# 1. 装 Bun（运行时——只有 Node 不行）
+# 1. 装 Bun（运行时，只有 Node 不行）
 curl -fsSL https://bun.sh/install | bash
 # 2. 装 CLI。postinstall 会自动注册 Claude Code 插件市场并安装插件
 #    （best-effort;需要本机已有 bun + claude）。
 npm install -g @raysonmeng/agentbridge
-# 3. 启动 Claude Code 并启用 AgentBridge channel
+# 3. 初始化项目(检查依赖、必要时补装插件、写入 .agentbridge/config.json)
+abg init
+# 4. 启动 Claude Code 并启用 AgentBridge channel
 abg claude
-# 4. 在另一个终端启动 Codex TUI 连接同一个 bridge
+# 5. 在另一个终端启动 Codex TUI 连接同一个 bridge
 abg codex
 ```
-就这样——daemon 会在需要时自动启动，重启后自动重连。（`abg` 是 `agentbridge` 的简写别名，两者完全等价。）如果 postinstall 的插件步骤被跳过（比如当时还没装 Claude Code），运行 `abg init` 重试，或见 [手动安装插件（兜底）](#手动安装插件兜底)。
+就这样：daemon 会在需要时自动启动，重启后自动重连。（`abg` 是 `agentbridge` 的简写别名，两者完全等价。）如果 postinstall 的插件步骤被跳过（比如当时还没装 Claude Code），运行 `abg init` 重试，或见 [手动安装插件（兜底）](#手动安装插件兜底)。
 > [!WARNING]
-> **`abg claude` 默认带 `--dangerously-skip-permissions` 启动，`abg codex` 默认带 `--yolo` 启动。** 这是故意的——无人值守的 agent 对没法为每个权限停下来问你——但这意味着两个 agent 都能**不经询问**执行命令、改文件。只在你信任的工作区里这么用。要恢复正常询问，加 `--safe`（`abg claude --safe`、`abg codex --safe`）或设 `AGENTBRIDGE_SAFE=1`；你自己显式传权限参数时,默认值也会被自动抑制。
+> **`abg claude` 默认带 `--dangerously-skip-permissions` 启动，`abg codex` 默认带 `--yolo` 启动。** 这是故意的：无人值守的 agent 对没法为每个权限停下来问你。这意味着两个 agent 都能**不经询问**执行命令、改文件。只在你信任的工作区里这么用。要恢复正常询问，加 `--safe`（`abg claude --safe`、`abg codex --safe`）或设 `AGENTBRIDGE_SAFE=1`；你自己显式传权限参数时,默认值也会被自动抑制。
 ### 你的第一次协作
@@ -93,7 +115,7 @@ abg codex
 > **对 Claude 说：** *「为 &lt;你的任务&gt; 和 Codex 提一个分工方案，然后让 Codex 实现它那部分、你来 review。」*
-你应该会看到：Claude 把一个分工提案发进 Codex 会话、Codex 接受（或反提议）并开始干活、Codex 完成后推回 Claude 会话让它 review——全程不用你手动中转任何东西。
+你应该会看到：Claude 把一个分工提案发进 Codex 会话、Codex 接受（或反提议）并开始干活、Codex 完成后推回 Claude 会话让它 review，全程不用你手动中转任何东西。
 ### 手动安装插件（兜底）
@@ -150,9 +172,9 @@ agentbridge codex   # （另一个终端）启动 Codex TUI 连接 Bridge
 ### 跨网协作 *(v3 预览)*
-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)。
+v3 协作层随 **0.1.31** 发布：通过 broker 连接跨机器共享房间，提供 `auth` / `broker` / `room` / `join` / `publish` 命令。只有 Codex 的机器也能通过原生房间工具收发消息和 ACK。配置方法及投递边界见 [Codex 跨机房间](docs/CODEX-ROOMS.md)，broker 和成员管理见 [使用手册](docs/manual/使用手册.md)。
-成对命令（`claude`、`codex`、`resume`、`kill`、`doctor`、`budget`、`logs`）接受 `--pair <name>` 指定具体的对——默认每个项目目录一对，端口按 +10 步长从 4500 分配。
+成对命令（`claude`、`codex`、`resume`、`kill`、`doctor`、`budget`、`logs`）接受 `--pair <name>` 指定具体的对；默认每个项目目录一对，端口按 +10 步长从 4500 分配。
 ### Owned flags
@@ -160,7 +182,7 @@ v3 协作层(跨机器/跨 agent 的共享房间,含 `auth` / `broker` / `room`
 - `agentbridge claude` 拥有：`--channels`、`--dangerously-load-development-channels`
 - `agentbridge codex` 拥有：`--remote`、`--enable tui_app_server`
-- 两个启动器都消费包装参数 `--safe`（永不透传）：它关闭该次启动的最大权限默认值。当你自己显式传任何权限参数时（codex 的 `-a`/`--ask-for-approval`/`-s`/`--sandbox`；claude 的 `--permission-mode`/`--allow-dangerously-skip-permissions`），默认值也会自动抑制——在显式审批策略旁再注入 `--yolo` 会触发 codex CLI 硬冲突。
+- 两个启动器都消费包装参数 `--safe`（永不透传）：它关闭该次启动的最大权限默认值。当你自己显式传任何权限参数时（codex 的 `-a`/`--ask-for-approval`/`-s`/`--sandbox`；claude 的 `--permission-mode`/`--allow-dangerously-skip-permissions`），默认值也会自动抑制；在显式审批策略旁再注入 `--yolo` 会触发 codex CLI 硬冲突。
 手动传入被拥有的参数会报错，并提示使用原生命令。
@@ -170,8 +192,8 @@ v3 协作层(跨机器/跨 agent 的共享房间,含 `auth` / `broker` / `room`
 AgentBridge 是一个**两进程**本地 Bridge：
-- **bridge.ts** —— 由 Claude Code 通过 AgentBridge 插件启动的前台 MCP 客户端，Claude Code 关闭时退出。
-- **daemon.ts** —— 常驻本地后台进程，持有 Codex app-server 代理和桥接状态这一唯一真源。跨 Claude Code 重启存活；`bridge.ts` 以指数退避重连。
+- **bridge.ts**：由 Claude Code 通过 AgentBridge 插件启动的前台 MCP 客户端，Claude Code 关闭时退出。
+- **daemon.ts**：常驻本地后台进程，持有 Codex app-server 代理和桥接状态这一唯一真源。跨 Claude Code 重启存活；`bridge.ts` 以指数退避重连。
 ```
 ┌──────────────┐    MCP stdio / plugin     ┌────────────────────┐
@@ -251,11 +273,11 @@ daemon 在平台感知的目录中存储运行时状态：
 ## 额度协调与自动续接
-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 才启用。
+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 即启用。
-- **快照** —— daemon 经 guard 的探针轮询两侧账号级 5h/周额度；`abg budget [--json]` 打印实时快照（两个窗口、漂移、暂停态）。只要装了 guard 的探针就能用。
-- **减速线（中途不腰斩）** —— 接近额度硬线时，guard **不**在工具调用中途 deny，而是让当前 turn 跑完、在回合边界干净停下、写 `.agent/checkpoint.md`，并落一条 bridge 能检测的 `pending` 记录。
-- **全自动续接** —— 被暂停一侧窗口刷新后，bridge 在**原本的交互式 TUI** 里续接：Codex 经排队的 `turn/start` 注入，Claude 经 channel push 并由 `ack_resume` 回执。每条 pending 的幂等墓碑保证同一续接最多注入一次，跨 daemon 重启亦然。
+- **快照**：daemon 经 guard 的探针轮询两侧账号级 5h/周额度；`abg budget [--json]` 打印实时快照（两个窗口、漂移、暂停态）。只要装了 guard 的探针就能用。
+- **减速线（中途不腰斩）**：接近额度硬线时，guard **不**在工具调用中途 deny，而是让当前 turn 跑完、在回合边界干净停下、写 `.agent/checkpoint.md`，并落一条 bridge 能检测的 `pending` 记录。
+- **全自动续接**：被暂停一侧窗口刷新后，bridge 在**原本的交互式 TUI** 里续接：Codex 经排队的 `turn/start` 注入，Claude 经 channel push 并由 `ack_resume` 回执。每条 pending 的幂等墓碑保证同一续接最多注入一次，跨 daemon 重启亦然。
 > **实验性 / opt-in。** 这是依赖配套 guard 的能力。Claude 侧续接是 best-effort（ack + 重试 + `SessionStart` 兜底）：对完全空闲会话的 channel push 存在已知上游不确定性，故 bridge 只有看到真正的 `ack_resume` 才标记该侧已续接。
@@ -270,16 +292,16 @@ AgentBridge 能让长任务跨订阅额度窗口持续推进，而不是某一
 ## Roadmap
-- **更多 adapter** —— 今天 AgentBridge 接的是 Claude Code ↔ Codex。下一个候选：**OpenCode、OpenClaw、Hermes Agent、Gemini CLI**。到 [adapter roadmap issue](https://github.com/quilin-ai/agent-bridge/issues/212) 投票。
-- **能力网格（Capability mesh）** —— 超越消息传递：连上的 agent 会发布自己的命令 / skills / MCP tools，让对等体直接调用——从「传消息」走向「调能力」。
-- **v2 —— 多 Agent 基础设施**（部分已落地）：Room 作用域协作、稳定身份、正式控制协议、更强恢复。见 [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md)。
-- **v3 —— 跨网协作**（preview，见上面的实验性 CLI）：跨机器、跨 agent 的共享房间，经 broker。见 [docs/09-v3协作系统规格.md](docs/09-v3协作系统规格.md)。
+- **更多 adapter**：今天 AgentBridge 接的是 Claude Code ↔ Codex。下一个候选：**OpenCode、OpenClaw、Hermes Agent、Gemini CLI**。到 [adapter roadmap issue](https://github.com/raysonmeng/agent-bridge/issues/212) 投票。
+- **能力网格（Capability mesh）**：超越消息传递：连上的 agent 会发布自己的命令 / skills / MCP tools，让对等体直接调用，从「传消息」走向「调能力」。
+- **v2：多 Agent 基础设施**（部分已落地）：Room 作用域协作、稳定身份、正式控制协议、更强恢复。见 [docs/08-v2架构愿景.md](docs/08-v2架构愿景.md)。
+- **v3：跨网协作**（已包含于 0.1.31，实验性）：跨机器、跨 agent 的共享房间，经 broker。见 [Codex 跨机房间](docs/CODEX-ROOMS.md)。
 ## 文档
-- **[排错 / Troubleshooting](docs/TROUBLESHOOTING.md)** —— 禁用状态恢复、Codex `.git` 挂死、「装了却跑不起来」、Bun 版本要求
-- **[使用手册](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)）—— 端到端使用走查
-- **[项目成长编年史](docs/README.md)** —— AgentBridge 是怎么一步步长起来的（阶段 01–11）
+- **[排错 / Troubleshooting](docs/TROUBLESHOOTING.md)**：禁用状态恢复、Codex `.git` 挂死、「装了却跑不起来」、Bun 版本要求
+- **[使用手册](docs/manual/使用手册.md)**（[English](docs/manual/manual-en.md)）：端到端使用走查
+- **[项目成长编年史](docs/README.md)**：AgentBridge 是怎么一步步长起来的（阶段 01–11）
 ## 这个项目是怎么建成的
@@ -289,6 +311,7 @@ AgentBridge 能让长任务跨订阅额度窗口持续推进，而不是某一
 这是我首次开源的项目！欢迎对多 Agent 协作、AI 工具链感兴趣的朋友来交流，一起做一些更好玩的事情。
+- **个人网站**: [raysonmeng.pages.dev](https://raysonmeng.pages.dev/)
 - **Twitter/X**: [@raysonmeng](https://x.com/raysonmeng)
 - **小红书**: [主页](https://www.xiaohongshu.com/user/profile/62a3709d0000000021028b7e)
 - **微信**: 扫描下方二维码添加好友