@raysonmeng/agentbridge 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "agentbridge",
+  "owner": {
+    "name": "AgentBridge Contributors",
+    "email": "raysonmeng@qq.com",
+    "url": "https://github.com/raysonmeng/agent-bridge"
+  },
+  "metadata": {
+    "description": "Marketplace for the AgentBridge Claude Code plugin and supporting runtime integration."
+  },
+  "plugins": [
+    {
+      "name": "agentbridge",
+      "description": "Bridge Claude Code and Codex through a shared daemon, push channel delivery, and reply/get_messages tools.",
+      "version": "0.1.0",
+      "author": {
+        "name": "AgentBridge Contributors",
+        "email": "raysonmeng@qq.com"
+      },
+      "source": "./plugins/agentbridge",
+      "category": "development"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentBridge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# AgentBridge
+
+[![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)
+
+[中文文档](README.zh-CN.md)
+
+Local bridge for bidirectional communication between Claude Code and Codex inside the same working session.
+
+AgentBridge uses a two-process architecture:
+
+- **bridge.ts** is the foreground MCP client started by Claude Code via the AgentBridge plugin
+- **daemon.ts** is a persistent local background process that owns the Codex app-server proxy and bridge state
+
+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.
+
+## What this project is / is not
+
+**This project is:**
+
+- A local developer tool for connecting Claude Code and Codex in one workflow
+- A bridge that forwards messages between an MCP channel and the Codex app-server protocol
+- An experimental setup for human-in-the-loop collaboration between multiple agents
+
+**This project is not:**
+
+- A hosted service or multi-tenant system
+- A generic orchestration framework for arbitrary agent backends
+- A hardened security boundary between tools you do not trust
+
+## Architecture
+
+```
+┌──────────────┐     MCP stdio / plugin     ┌────────────────────┐
+│ Claude Code  │ ──────────────────────────▶ │ bridge.ts          │
+│ Session      │ ◀──────────────────────────  │ foreground client  │
+└──────────────┘                             └─────────┬──────────┘
+                                                       │
+                                                       │ control WS (:4502)
+                                                       ▼
+                                             ┌────────────────────┐
+                                             │ daemon.ts          │
+                                             │ bridge daemon      │
+                                             └─────────┬──────────┘
+                                                       │
+                                     ws://127.0.0.1:4501 proxy
+                                                       │
+                                                       ▼
+                                             ┌────────────────────┐
+                                             │ Codex app-server   │
+                                             └────────────────────┘
+```
+
+### Data flow
+
+| Direction | Path |
+|-----------|------|
+| **Codex -> Claude** | `daemon.ts` captures `agentMessage` -> control WS -> `bridge.ts` -> `notifications/claude/channel` |
+| **Claude -> Codex** | Claude calls the `reply` tool -> `bridge.ts` -> control WS -> `daemon.ts` -> `turn/start` injects into the Codex thread |
+
+### Loop prevention
+
+Each message carries a `source` field (`"claude"` or `"codex"`). The bridge never forwards a message back to its origin.
+
+## Prerequisites
+
+| Dependency | Version | Install |
+|-----------|---------|---------|
+| [Bun](https://bun.sh) | v1.0+ | `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` |
+
+> **Note:** Bun is required as the runtime for the AgentBridge daemon and plugin server. Node.js alone is not sufficient.
+
+## Quick Start
+
+### Install via Plugin Marketplace (recommended)
+
+Install AgentBridge directly from Claude Code using the plugin marketplace:
+
+```bash
+# 1. In Claude Code, add the AgentBridge marketplace
+/plugin marketplace add raysonmeng/agent-bridge
+
+# 2. Install the plugin
+/plugin install agentbridge@agentbridge
+
+# 3. Reload plugins to activate
+/reload-plugins
+```
+
+Then install the CLI tool:
+
+```bash
+# 4. Install the CLI globally
+npm install -g agentbridge
+
+# 5. Generate project config (optional)
+abg init
+
+# 6. Start Claude Code with AgentBridge channel enabled
+abg claude
+
+# 7. Start Codex TUI connected to the bridge (in another terminal)
+abg codex
+```
+
+> **Tip:** `abg` is a short alias for `agentbridge`. Both commands are identical — use whichever you prefer.
+
+That's it. The daemon starts automatically when needed and reconnects if restarted.
+
+#### Updating the plugin
+
+When a new version is released, update from Claude Code:
+
+```bash
+/plugin marketplace update agentbridge
+/reload-plugins
+```
+
+Or enable auto-update: run `/plugin` → **Marketplaces** tab → select **agentbridge** → **Enable auto-update**.
+
+### Install for local development
+
+If you want to modify AgentBridge source code, use the local development setup instead:
+
+```bash
+# 1. Clone and install dependencies
+git clone https://github.com/raysonmeng/agent-bridge.git
+cd agent-bridge
+bun install
+bun link
+
+# 2. Set up local plugin + project config
+agentbridge dev     # Register local marketplace + install plugin
+agentbridge init    # Check dependencies, generate .agentbridge/config.json
+
+# 3. Start Claude Code with AgentBridge plugin loaded
+agentbridge claude
+
+# 4. Start Codex TUI connected to the bridge (in another terminal)
+agentbridge codex
+```
+
+> **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.
+
+#### Updating after code changes
+
+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.
+
+## CLI Reference
+
+> All commands work with both `agentbridge` and the short alias `abg`.
+
+| Command | Description |
+|---------|-------------|
+| `abg init` | Install plugin, check dependencies (bun/claude/codex), generate `.agentbridge/config.json` and `collaboration.md` |
+| `abg claude [args...]` | Start Claude Code with push channel enabled. Clears any killed sentinel from a previous `kill`. Pass-through args are forwarded to `claude` |
+| `abg codex [args...]` | Start Codex TUI connected to AgentBridge daemon. Manages TUI process lifecycle (pid tracking, cleanup). Pass-through args forwarded to `codex` |
+| `abg kill` | Gracefully stop both daemon and managed Codex TUI, clean up state files, write killed sentinel |
+| `abg dev` | (Dev only) Register local marketplace + force-sync plugin to cache |
+| `abg --help` | Show help |
+| `abg --version` | Show version |
+
+### Owned flags
+
+Some flags are automatically injected and cannot be manually specified:
+
+- `agentbridge claude` owns: `--channels`, `--dangerously-load-development-channels`
+- `agentbridge codex` owns: `--remote`, `--enable tui_app_server`
+
+Passing these flags manually will result in a hard error with guidance to use the native command directly.
+
+## Project Config
+
+Running `agentbridge init` creates a `.agentbridge/` directory in your project root:
+
+| File | Purpose |
+|------|---------|
+| `config.json` | Machine-readable project config (ports, agent roles, markers, turn coordination) |
+| `collaboration.md` | Human/agent-readable collaboration rules (roles, thinking patterns, communication style) |
+
+The config is loaded by the CLI and daemon at startup. Re-running `init` is idempotent and will not overwrite existing files.
+
+## File Structure
+
+```
+agent_bridge/
+├── .github/
+│   ├── ISSUE_TEMPLATE/           # Bug report and feature request templates
+│   ├── pull_request_template.md
+│   └── workflows/ci.yml          # GitHub Actions CI
+├── assets/                        # Static assets (images, etc.)
+├── docs/
+│   ├── phase3-spec.md            # Phase 3 design spec (CLI + Plugin)
+│   ├── v1-roadmap.md             # v1 feature roadmap
+│   └── v2-architecture.md        # v2 multi-agent architecture design
+├── plugins/agentbridge/           # Claude Code plugin bundle
+│   ├── .claude-plugin/plugin.json
+│   ├── commands/init.md
+│   ├── hooks/hooks.json
+│   ├── scripts/health-check.sh
+│   └── server/                    # Bundled bridge-server.js + daemon.js
+├── src/
+│   ├── bridge.ts                  # Claude foreground MCP client (plugin entry point)
+│   ├── daemon.ts                  # Persistent background daemon
+│   ├── daemon-client.ts           # WebSocket client for daemon control port
+│   ├── daemon-lifecycle.ts        # Shared daemon lifecycle (ensureRunning, kill, startup lock)
+│   ├── control-protocol.ts        # Foreground/background control protocol types
+│   ├── claude-adapter.ts          # MCP server adapter for Claude Code channels
+│   ├── codex-adapter.ts           # Codex app-server WebSocket proxy and message interception
+│   ├── config-service.ts          # Project config (.agentbridge/) read/write
+│   ├── state-dir.ts               # Platform-aware state directory resolver
+│   ├── message-filter.ts          # Smart message filtering (markers, summary buffer)
+│   ├── types.ts                   # Shared types
+│   ├── cli.ts                     # CLI entry point and command router
+│   └── cli/
+│       ├── init.ts                # agentbridge init
+│       ├── claude.ts              # agentbridge claude
+│       ├── codex.ts               # agentbridge codex
+│       ├── kill.ts                # agentbridge kill
+│       └── dev.ts                 # agentbridge dev
+├── CLAUDE.md                      # Project rules for AI agents
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── README.md
+├── README.zh-CN.md
+├── SECURITY.md
+├── package.json
+└── tsconfig.json
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_WS_PORT` | `4500` | Codex app-server WebSocket port |
+| `CODEX_PROXY_PORT` | `4501` | Bridge proxy port for the Codex TUI |
+| `AGENTBRIDGE_CONTROL_PORT` | `4502` | Control port between bridge.ts and daemon.ts |
+| `AGENTBRIDGE_STATE_DIR` | Platform default | State directory for pid, status, logs (macOS: `~/Library/Application Support/agentbridge/`, Linux: `$XDG_STATE_HOME/agentbridge/`) |
+| `AGENTBRIDGE_MODE` | `push` | Message delivery mode (`push` for channels, `pull` for API key mode) |
+| `AGENTBRIDGE_DAEMON_ENTRY` | `./daemon.ts` | Override daemon entry point (used by plugin bundles) |
+
+### State Directory
+
+The daemon stores runtime state in a platform-aware directory:
+
+| Platform | Default Path |
+|----------|-------------|
+| macOS | `~/Library/Application Support/agentbridge/` |
+| Linux | `$XDG_STATE_HOME/agentbridge/` (fallback: `~/.local/state/agentbridge/`) |
+
+Contents: `daemon.pid`, `status.json`, `agentbridge.log`, `killed` (sentinel), `startup.lock`
+
+## Current Limitations
+
+- Only forwards `agentMessage` items, not intermediate `commandExecution`, `fileChange`, or similar events
+- Single Codex thread, no multi-session support yet
+- Single Claude foreground connection; a new Claude session replaces the previous one
+- Fixed ports mean only one AgentBridge instance per machine (multi-project support planned for post-v1)
+
+### Codex git restrictions
+
+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.
+
+**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.
+
+## Roadmap
+
+- **v1.x (current)**: Improve the single-bridge experience without architectural refactoring -- less noise, better turn discipline, and clearer collaboration modes. See [docs/v1-roadmap.md](docs/v1-roadmap.md).
+- **v2 (planned)**: Introduce the multi-agent foundation -- room-scoped collaboration, stable identity, a formal control protocol, and stronger recovery semantics. See [docs/v2-architecture.md](docs/v2-architecture.md).
+- **v3+ (longer term)**: Explore smarter collaboration, richer policies, and more advanced orchestration across runtimes.
+
+## 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.
+
+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.
+
+## 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:
+
+- **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
+
+<img src="assets/wechat-qr.jpg" alt="WeChat QR Code" width="300" />

package/README.zh-CN.md

@@ -0,0 +1,291 @@
+# AgentBridge
+
+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)
+
+让 Claude Code 和 Codex 在同一个工作会话中进行双向通信的本地 Bridge。
+
+AgentBridge 采用两层进程结构：
+
+- **bridge.ts** 是由 Claude Code 通过 AgentBridge 插件启动的前台 MCP 客户端
+- **daemon.ts** 是常驻本地的后台进程，持有 Codex app-server 代理和桥接状态
+
+当 Claude Code 关闭时，前台 MCP 进程退出，后台 daemon 与 Codex 代理继续存活。当 Claude Code 再次启动时，会自动重连（指数退避）。
+
+## 这个项目是什么 / 不是什么
+
+**这个项目是：**
+
+- 一个把 Claude Code 和 Codex 连接到同一工作流里的本地开发工具
+- 一个在 MCP channel 与 Codex app-server 协议之间转发消息的桥接层
+- 一个面向人工参与、多代理协作场景的实验性方案
+
+**这个项目不是：**
+
+- 一个托管服务或多租户系统
+- 一个面向任意 Agent 后端的通用编排框架
+- 一个可以隔离不可信工具的强化安全边界
+
+## 架构
+
+```
+┌──────────────┐    MCP stdio / plugin     ┌────────────────────┐
+│ Claude Code  │ ─────────────────────────▶ │ bridge.ts          │
+│ Session      │ ◀─────────────────────────  │ 前台 MCP 客户端     │
+└──────────────┘                            └─────────┬──────────┘
+                                                      │
+                                                      │ 控制 WS (:4502)
+                                                      ▼
+                                            ┌────────────────────┐
+                                            │ daemon.ts          │
+                                            │ 常驻后台桥接进程    │
+                                            └─────────┬──────────┘
+                                                      │
+                                    ws://127.0.0.1:4501 proxy
+                                                      │
+                                                      ▼
+                                            ┌────────────────────┐
+                                            │ Codex app-server   │
+                                            └────────────────────┘
+```
+
+### 数据流
+
+| 方向 | 链路 |
+|------|------|
+| **Codex -> Claude** | `daemon.ts` 捕获 `agentMessage` -> 控制 WS -> `bridge.ts` -> `notifications/claude/channel` |
+| **Claude -> Codex** | Claude 调用 `reply` tool -> `bridge.ts` -> 控制 WS -> `daemon.ts` -> `turn/start` 注入 Codex thread |
+
+### 防循环
+
+每条消息都携带 `source` 字段（`"claude"` 或 `"codex"`），Bridge 永远不会把消息转发回它的来源。
+
+## 前置条件
+
+| 依赖 | 版本 | 安装方式 |
+|------|------|----------|
+| [Bun](https://bun.sh) | v1.0+ | `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` |
+
+> **注意：** Bun 是 AgentBridge daemon 和插件服务器的必要运行时，仅有 Node.js 不够。
+
+## Quick Start
+
+### 通过插件市场安装（推荐）
+
+在 Claude Code 中直接安装 AgentBridge 插件：
+
+```bash
+# 1. 在 Claude Code 中，添加 AgentBridge 市场
+/plugin marketplace add raysonmeng/agent-bridge
+
+# 2. 安装插件
+/plugin install agentbridge@agentbridge
+
+# 3. 重新加载插件以激活
+/reload-plugins
+```
+
+然后安装 CLI 工具：
+
+```bash
+# 4. 全局安装 CLI
+npm install -g agentbridge
+
+# 5. 生成项目配置（可选）
+abg init
+
+# 6. 启动 Claude Code（自动加载 AgentBridge channel）
+abg claude
+
+# 7. 在另一个终端启动 Codex TUI 连接 Bridge
+abg codex
+```
+
+> **提示：** `abg` 是 `agentbridge` 的简写别名，两个命令完全等价，用哪个都行。
+
+就这样。Daemon 会在需要时自动启动，重启后自动重连。
+
+#### 更新插件
+
+新版本发布后，在 Claude Code 中更新：
+
+```bash
+/plugin marketplace update agentbridge
+/reload-plugins
+```
+
+或启用自动更新：执行 `/plugin` → **Marketplaces** 标签页 → 选择 **agentbridge** → **Enable auto-update**。
+
+### 本地开发安装
+
+如需修改 AgentBridge 源码，使用本地开发模式：
+
+```bash
+# 1. 克隆并安装依赖
+git clone https://github.com/raysonmeng/agent-bridge.git
+cd agent-bridge
+bun install
+bun link
+
+# 2. 安装本地插件 + 生成项目配置
+agentbridge dev     # 注册本地 marketplace + 安装插件
+agentbridge init    # 检查依赖、生成 .agentbridge/config.json
+
+# 3. 启动 Claude Code（自动加载 AgentBridge 插件）
+agentbridge claude
+
+# 4. 在另一个终端启动 Codex TUI 连接 Bridge
+agentbridge codex
+```
+
+> **注意：** `agentbridge claude` 会自动注入 `--dangerously-load-development-channels plugin:agentbridge@agentbridge`。这会把本地开发中的 channel 挂载进 Claude Code（当前属于 Research Preview）。请只启用你信任的 channel 和 MCP server。
+
+#### 修改代码后更新
+
+修改 AgentBridge 源码后，重新执行 `agentbridge dev` 同步插件到缓存，然后重启 Claude Code 或在活跃会话中执行 `/reload-plugins`。
+
+## CLI 命令参考
+
+> 所有命令同时支持 `agentbridge` 和简写别名 `abg`。
+
+| 命令 | 说明 |
+|------|------|
+| `abg init` | 安装插件、检查依赖（bun/claude/codex）、生成 `.agentbridge/config.json` 和 `collaboration.md` |
+| `abg claude [args...]` | 启动 Claude Code 并启用 push channel。自动清除之前 `kill` 留下的 sentinel。额外参数透传给 `claude` |
+| `abg codex [args...]` | 启动连接到 AgentBridge daemon 的 Codex TUI。管理 TUI 进程生命周期（pid 跟踪、清理）。额外参数透传给 `codex` |
+| `abg kill` | 优雅停止 daemon 和托管的 Codex TUI，清理状态文件，写入 killed sentinel |
+| `abg dev` | （开发用）注册本地 marketplace + 强制同步插件到缓存 |
+| `abg --help` | 显示帮助 |
+| `abg --version` | 显示版本 |
+
+### Owned flags
+
+部分参数由 CLI 自动注入，不可手动指定：
+
+- `agentbridge claude` 拥有：`--channels`、`--dangerously-load-development-channels`
+- `agentbridge codex` 拥有：`--remote`、`--enable tui_app_server`
+
+手动传入这些参数会报错，并提示使用原生命令。
+
+## 项目配置
+
+运行 `agentbridge init` 会在项目根目录创建 `.agentbridge/` 目录：
+
+| 文件 | 用途 |
+|------|------|
+| `config.json` | 机器可读的项目配置（端口、Agent 角色、消息标记、回合协调） |
+| `collaboration.md` | 人类/Agent 可读的协作规则（角色、思考模式、沟通风格） |
+
+CLI 和 daemon 启动时会加载该配置。重复运行 `init` 是幂等的，不会覆盖已有文件。
+
+## 文件结构
+
+```
+agent_bridge/
+├── .github/
+│   ├── ISSUE_TEMPLATE/           # Bug report 和 feature request 模板
+│   ├── pull_request_template.md
+│   └── workflows/ci.yml          # GitHub Actions CI
+├── assets/                        # 图片资源
+├── docs/
+│   ├── phase3-spec.md            # Phase 3 设计文档（CLI + Plugin）
+│   ├── v1-roadmap.md             # v1 功能路线图
+│   └── v2-architecture.md        # v2 多 Agent 架构设计
+├── plugins/agentbridge/           # Claude Code 插件包
+│   ├── .claude-plugin/plugin.json
+│   ├── commands/init.md
+│   ├── hooks/hooks.json
+│   ├── scripts/health-check.sh
+│   └── server/                    # 打包的 bridge-server.js + daemon.js
+├── src/
+│   ├── bridge.ts                  # Claude 前台 MCP 客户端（插件入口）
+│   ├── daemon.ts                  # 常驻后台 daemon
+│   ├── daemon-client.ts           # daemon 控制端口的 WebSocket 客户端
+│   ├── daemon-lifecycle.ts        # 共享 daemon 生命周期（ensureRunning、kill、启动锁）
+│   ├── control-protocol.ts        # 前后台控制协议类型
+│   ├── claude-adapter.ts          # Claude Code channel 的 MCP server 适配层
+│   ├── codex-adapter.ts           # Codex app-server WebSocket 代理与消息拦截
+│   ├── config-service.ts          # 项目配置（.agentbridge/）读写
+│   ├── state-dir.ts               # 平台感知的状态目录解析
+│   ├── message-filter.ts          # 智能消息过滤（标记、摘要缓冲）
+│   ├── types.ts                   # 共享类型
+│   ├── cli.ts                     # CLI 入口和命令路由
+│   └── cli/
+│       ├── init.ts                # agentbridge init
+│       ├── claude.ts              # agentbridge claude
+│       ├── codex.ts               # agentbridge codex
+│       ├── kill.ts                # agentbridge kill
+│       └── dev.ts                 # agentbridge dev
+├── CLAUDE.md                      # AI Agent 项目规则
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── README.md
+├── README.zh-CN.md
+├── SECURITY.md
+├── package.json
+└── tsconfig.json
+```
+
+## 配置
+
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `CODEX_WS_PORT` | `4500` | Codex app-server WebSocket 端口 |
+| `CODEX_PROXY_PORT` | `4501` | Bridge 代理端口，Codex TUI 连接此端口 |
+| `AGENTBRIDGE_CONTROL_PORT` | `4502` | bridge.ts 与 daemon.ts 之间的控制端口 |
+| `AGENTBRIDGE_STATE_DIR` | 平台默认 | 状态目录（pid、status、日志）。macOS: `~/Library/Application Support/agentbridge/`，Linux: `$XDG_STATE_HOME/agentbridge/` |
+| `AGENTBRIDGE_MODE` | `push` | 消息投递模式（`push` 用于 channel，`pull` 用于 API key 模式） |
+| `AGENTBRIDGE_DAEMON_ENTRY` | `./daemon.ts` | 覆盖 daemon 入口（插件包使用） |
+
+### 状态目录
+
+daemon 在平台感知的目录中存储运行时状态：
+
+| 平台 | 默认路径 |
+|------|---------|
+| macOS | `~/Library/Application Support/agentbridge/` |
+| Linux | `$XDG_STATE_HOME/agentbridge/`（回退：`~/.local/state/agentbridge/`） |
+
+内容：`daemon.pid`、`status.json`、`agentbridge.log`、`killed`（sentinel）、`startup.lock`
+
+## 当前限制
+
+- 目前只转发 `agentMessage`，不转发 `commandExecution`、`fileChange` 等中间过程事件
+- 当前只支持单个 Codex thread，不支持多会话
+- 当前只支持单个 Claude 前台连接；新的 Claude 会话会替换旧连接
+- 固定端口意味着每台机器只能运行一个 AgentBridge 实例（多项目并行支持计划在 v1 之后）
+
+### Codex 的 Git 操作限制
+
+Codex 运行在沙箱环境中，**禁止对 `.git` 目录进行任何写操作**。这意味着 Codex 无法执行 `git commit`、`git push`、`git pull`、`git checkout -b`、`git merge` 等任何修改 Git 元数据的命令。尝试执行这些命令会导致 Codex 会话无限期挂起。
+
+**建议做法：** 让 Claude Code 负责所有 Git 操作（创建分支、提交、推送、创建 PR）。Codex 专注于代码修改，通过 `agentMessage` 汇报完成的工作，由 Claude Code 负责 Git 工作流。
+
+## Roadmap
+
+- **v1.x（当前）**：在不改变架构的前提下优化单桥体验 -- 降噪、控回合、定角色。详见 [docs/v1-roadmap.md](docs/v1-roadmap.md)。
+- **v2（规划中）**：引入多 Agent 基础设施 -- Room 作用域协作、稳定身份、正式控制协议、更强的恢复语义。详见 [docs/v2-architecture.md](docs/v2-architecture.md)。
+- **v3+（远期）**：更智能的协作、更丰富的策略、跨 runtime 的高级编排。
+
+## 这个项目是怎么建成的
+
+这个项目由 **Claude Code**（Anthropic）和 **Codex**（OpenAI）通过 AgentBridge 本身进行实时双向通信，在人类开发者的指挥下协作完成。开发者负责分配任务、审查进度，并指挥两个 Agent 并行工作、互相 review。
+
+换句话说，AgentBridge 就是它自己的 proof of concept：两个来自不同厂商的 AI Agent，通过实时连接，肩并肩地交付代码。
+
+## 联系方式
+
+这是我首次开源的项目！欢迎对多 Agent 协作、AI 工具链感兴趣的朋友来交流，一起做一些更好玩的事情。
+
+- **Twitter/X**: [@raysonmeng](https://x.com/raysonmeng)
+- **小红书**: [主页](https://www.xiaohongshu.com/user/profile/62a3709d0000000021028b7e)
+- **微信**: 扫描下方二维码添加好友
+
+<img src="assets/wechat-qr.jpg" alt="微信二维码" width="300" />