chore: dual-host plugin (Claude + Codex) via Node.js MCP bridge

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "ccteam",
       "description": "Multi-vendor (Claude + Codex) AI team orchestration on Claude Code — MCP-driven, file-system-as-control-plane, chat-mode 24/7 IM bots.",
-      "version": "0.6.5",
+      "version": "0.6.6",
       "author": {
         "name": "FirstIntent"
       },
@@ -26,5 +26,5 @@
       ]
     }
   ],
-  "version": "0.6.5"
+  "version": "0.6.6"
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ccteam",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Multi-vendor AI team orchestration on Claude Code: 7 skills + 27 MCP tools + IM bots + multi-agent voting.",
   "author": {
     "name": "FirstIntent"

.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "ccteam",
+  "version": "0.6.6",
+  "description": "Multi-vendor (Claude + Codex) AI dev-team orchestration: 7 skills + 27 MCP tools + IM bots + dual-LLM voting.",
+  "author": {
+    "name": "FirstIntent"
+  },
+  "repository": "https://github.com/firstintent/ccteam",
+  "homepage": "https://github.com/firstintent/ccteam",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "claude-code",
+    "plugin",
+    "multi-agent",
+    "orchestration",
+    "mcp",
+    "telegram"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "ccteam",
+    "shortDescription": "Autonomous multi-agent dev team",
+    "longDescription": "An unattended multi-agent orchestration engine that drives software from intent to closed-loop delivery — Claude + Codex dual-vendor, file-system as control plane, 24/7 IM bots, dual-LLM voting.",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "brandColor": "#10A37F",
+    "defaultPrompt": [
+      "Use ccteam to scan this repo and tell me what it does",
+      "Use ccteam to run a long task overnight hands-off",
+      "Use ccteam to get a second opinion (Claude + Codex) on this design"
+    ]
+  }
+}

.mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "ccteam": {
-      "command": "ccteam",
-      "args": ["mcp-serve"]
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/index.js"]
     }
   }
 }

README.md

@@ -26,47 +26,48 @@ Not sure? Just describe it in natural language   /ccteam "<what you want>"
 
 ## Get started
 
-```bash
-# 0. Install Claude Code first: https://code.claude.com/docs/install
+### Install (Claude Code or Codex)
 
-# 1. Install the ccteam CLI binary (one line, no Rust toolchain needed):
-curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
-#    Installs to ~/.local/bin/ccteam. The script prints a PATH-export
-#    hint if that directory isn't on your PATH yet — follow it, then
-#    restart your shell (or `source ~/.bashrc` / `source ~/.zshrc`).
-#    Pin a specific release tag: CCTEAM_VERSION=<tag> curl ... | sh
-#    Install system-wide:        CCTEAM_INSTALL_DIR=/usr/local/bin curl ... | sh
-#    Or download an archive from https://github.com/firstintent/ccteam/releases
-#    Build from source instead (requires Rust 1.85+):
-#      cargo install --git https://github.com/firstintent/ccteam ccteam-cli
-
-# 2. Inside any Claude session, register the marketplace + install the plugin:
-claude
-```
+Inside any Claude Code session:
 
 ```
 /plugin marketplace add https://github.com/firstintent/ccteam
 /plugin install ccteam
 ```
 
+Inside any Codex session:
+
+```
+codex plugin marketplace add firstintent/ccteam
+```
+
+The plugin auto-downloads the Rust engine into its own sandbox on the first MCP invocation — no system-wide binary required, no Rust toolchain, no separate install step. A Node.js bridge (`index.js`) ships in the repo, detects the host (Claude vs Codex), pulls the matching prebuilt tarball from GitHub Releases, and execs `ccteam mcp-serve` under the covers. It also symlinks the binary to `~/.local/bin/ccteam` so the CLI is available from any terminal.
+
+### Use it
+
 ```
-# 3. Try the universal entry — describe what you want in any language:
+# Universal entry — describe what you want in any language:
 /ccteam "scan this repo and tell me what it does"
 /ccteam "fix the TypeScript errors in src/"
 /ccteam "build a Telegram bot that summarizes my GitHub PRs at 7am"
 
-# 4. (Optional) Bootstrap a per-project workflow scaffold from the CLI:
+# (Optional) Bootstrap a per-project workflow scaffold from the CLI:
 ccteam init <project>
 ```
 
-Supported platforms for the prebuilt binary: Linux x86_64, macOS arm64
-(Apple Silicon), macOS x86_64 (Intel). Windows users: install via WSL2
-and use the linux-x64 binary — native Windows isn't supported because
-tmux + inotify + POSIX signals are foundational to ccteam. On macOS,
-if Gatekeeper blocks the binary on first run:
-`xattr -d com.apple.quarantine ~/.local/bin/ccteam`.
+Supported platforms for the prebuilt binary: Linux x86_64, macOS arm64 (Apple Silicon), macOS x86_64 (Intel). Windows users: install via WSL2 and use the linux-x64 binary — native Windows isn't supported because tmux + inotify + POSIX signals are foundational to ccteam. On macOS, if Gatekeeper blocks the binary on first run: `xattr -d com.apple.quarantine ~/.local/bin/ccteam`.
+
+The plugin install registers the seven `/ccteam*` slash commands and `mcp__ccteam__*` MCP tools — they light up immediately. The 5-minute walkthrough for "private IM assistant" (the flagship use case) lives in [docs/quickstart.md](docs/quickstart.md).
+
+### Advanced: system-wide CLI without the plugin
+
+If you want `ccteam` on `$PATH` for daemon use (`ccteam start`) without going through a Claude or Codex session — for example on a headless server — install the binary directly:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
+```
 
-Step 2 registers ccteam as a Claude Code plugin marketplace, then installs the plugin — the seven `/ccteam*` slash commands and `mcp__ccteam__*` MCP tools light up immediately. The 5-minute walkthrough for "private IM assistant" (the flagship use case) lives in [docs/quickstart.md](docs/quickstart.md).
+Pin a tag: `CCTEAM_VERSION=<tag> curl ... | sh`. System-wide: `CCTEAM_INSTALL_DIR=/usr/local/bin curl ... | sh`. Or build from source: `cargo install --git https://github.com/firstintent/ccteam ccteam-cli` (Rust 1.85+).
 
 ## Three ways to talk to ccteam
 

docs/quickstart.md

@@ -116,62 +116,67 @@ ccteam probe-project --json    # 看 ccteam 怎么"看"你的仓库
 
 ## Step 1 — 装 ccteam plugin(30 秒)
 
-ccteam 走 Claude Code 官方 plugin marketplace 协议安装 —— **plugin 是首选路径**,CLI binary 作为前置条件先装好(plugin 通过 MCP 调用本机 `ccteam` 命令)。
+ccteam 走 Claude Code(或 Codex)官方 plugin 协议安装 —— **plugin 是首选**且唯一**必需**的入口。plugin 自带 Node.js bridge(`index.js`),首次在 MCP server 启动时探测宿主、按平台从 GitHub Release 拉对应 binary 到 plugin sandbox 内,然后 `exec ccteam mcp-serve`。**不需要预先装 CLI binary**(bridge 会顺手把 binary symlink 到 `~/.local/bin/ccteam`,所以装完 plugin 终端也直接能跑 `ccteam start`)。
 
-### 1.1 装 CLI binary(前置,一次性)
+### 1.1 在 Claude session 里注册 marketplace + 装 plugin
 
-**首选 ── 一行装预编译 binary(不需要 Rust toolchain):**
+任意 terminal 起 Claude session:
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
-ccteam --version    # 应输出当前版本号
+$ claude
 ```
 
-默认装到 `~/.local/bin/ccteam`。装完如果该路径不在 `$PATH`,脚本会打印一行 export 指令(贴进 `~/.bashrc` / `~/.zshrc` 再 `source` 即可)。
-
-支持的平台:Linux x86_64、macOS arm64(Apple Silicon)、macOS x86_64(Intel)。Windows 用户走 WSL2 + linux-x64 binary —— native Windows 不支持(tmux + inotify + POSIX signals 是 ccteam 架构根基)。
-
-环境变量:
-- `CCTEAM_INSTALL_DIR=/usr/local/bin sh install.sh` —— 改装目录(系统级安装)
-- `CCTEAM_VERSION=v0.6.6 sh install.sh` —— 装指定 tag(不取 latest)
+在 session 里依次输入:
 
-macOS Gatekeeper 拦截(首次跑报"not verified developer"):
-```bash
-xattr -d com.apple.quarantine ~/.local/bin/ccteam
+```
+/plugin marketplace add https://github.com/firstintent/ccteam
+/plugin install ccteam
 ```
 
-**回退 ── 从源码 build(需要 Rust 1.85+,5-15 min 编译):**
+预期输出:
 
-```bash
-cargo install --git https://github.com/firstintent/ccteam ccteam-cli
+```
+✓ Installed ccteam
+  • slash commands registered: /ccteam, /ccteam-team, /ccteam-creator, /ccteam-control, /ccteam-im-setup, /ccteam-scan, /ccteam-advise
+  • mcp__ccteam__* tools available (workflow_* / chat_* / advise_* / admin_* / screenshot_*)
 ```
 
-新机器没装 Rust 时,先 `curl https://sh.rustup.rs -sSf | sh` 装 rustup,然后再跑上面这条。
+首次调用任意 `mcp__ccteam__*` tool 时,`index.js` 会从 GitHub Release 拉对应平台的 tarball(linux-x64 / macos-arm64 / macos-x64),解压到 `${PLUGIN_ROOT}/bin/ccteam`,chmod +x,并 symlink 到 `~/.local/bin/ccteam`。第二次起秒启。
 
-### 1.2 在 Claude session 里注册 marketplace + 装 plugin
+跑 `ccteam doctor` 验装(claude CLI / MCP / tmux / pidfile 路径都查一遍);加 `--verify-mcp` 自检 MCP 工具表面齐全(应输出 `27 active, 0 stubs`,非零 exit 即 CI gate fail);加 `--check-codex-auto-critic` 验证 Codex 二审是否能开;加 `--check-cost-orphan` 对账 24h 内 ledger 与 progress.jsonl(catch spawn 路径漏写 ledger)。
 
-任意 terminal 起 Claude session:
+支持的平台:Linux x86_64、macOS arm64(Apple Silicon)、macOS x86_64(Intel)。Windows 用户走 WSL2 + linux-x64 binary —— native Windows 不支持(tmux + inotify + POSIX signals 是 ccteam 架构根基)。
 
+macOS Gatekeeper 拦截(首次跑报"not verified developer"):
 ```bash
-$ claude
+xattr -d com.apple.quarantine ~/.local/bin/ccteam
 ```
 
-在 session 里依次输入:
+### 1.2 Codex 用户
 
 ```
-/plugin marketplace add https://github.com/firstintent/ccteam
-/plugin install ccteam
+codex plugin marketplace add firstintent/ccteam
 ```
 
-预期输出:
+同一仓库同时是 Codex plugin。Bridge 通过 `CODEX_ACTIVE` env 嗅探宿主,自动选择走 Codex 路径。
 
-```
-✓ Installed ccteam
-  • slash commands registered: /ccteam, /ccteam-team, /ccteam-creator, /ccteam-control, /ccteam-im-setup, /ccteam-scan, /ccteam-advise
-  • mcp__ccteam__* tools available (workflow_* / chat_* / advise_* / admin_* / screenshot_*)
+### 1.3 高级:不走 plugin,直接装 system-wide CLI(可选)
+
+只想在终端 / 服务器跑 `ccteam start` daemon、不打算用 Claude/Codex skill 路径时:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh
+ccteam --version    # 应输出当前版本号
 ```
 
-跑 `ccteam doctor` 验装(claude CLI / MCP / tmux / pidfile 路径都查一遍);加 `--verify-mcp` 自检 MCP 工具表面齐全(应输出 `26 active, 0 stubs`,非零 exit 即 CI gate fail);加 `--check-codex-auto-critic` 验证 Codex 二审是否能开;加 `--check-cost-orphan` 对账 24h 内 ledger 与 progress.jsonl(catch spawn 路径漏写 ledger)。
+默认装到 `~/.local/bin/ccteam`。装完如果该路径不在 `$PATH`,脚本会打印一行 export 指令。环境变量:
+- `CCTEAM_INSTALL_DIR=/usr/local/bin sh install.sh` —— 改装目录(系统级安装)
+- `CCTEAM_VERSION=v0.6.6 sh install.sh` —— 装指定 tag(不取 latest)
+
+回退 ── 从源码 build(需要 Rust 1.85+,5-15 min 编译):
+```bash
+cargo install --git https://github.com/firstintent/ccteam ccteam-cli
+```
 
 → 卡了?见 [troubleshooting.md](troubleshooting.md) "plugin install 失败"。
 

docs/troubleshooting.md

@@ -21,7 +21,17 @@
 ### A3. `/plugin install ccteam@claude-plugins-official` 失败
 **原因**:网络 / GitHub rate-limit / 已装同名 plugin 冲突。
 **修复**:1) `/plugin list` 看是否同名 → `/plugin remove ccteam` 重装;2) 走代理 / 国内镜像;3) 仍失败:手动 `git clone` 到 `~/.claude/plugins/marketplaces/`。
-**相关**:A4 / A5。
+**相关**:A4 / A5 / A3b。
+
+### A3b. plugin 装好了,首次调 `mcp__ccteam__*` 时下载 binary 卡住 / 失败
+**原因**:plugin 的 Node.js bridge(`index.js`)首次 MCP 启动会从 GitHub Release 拉对应平台的 tarball(`ccteam-vX.Y.Z-<linux-x64|macos-arm64|macos-x64>.tar.gz`)到 `${PLUGIN_ROOT}/bin/ccteam`。慢/失败常因:1) GitHub Release 不在 CDN 近端(国内裸连慢);2) plugin sandbox 写权限缺;3) 平台 mismatch(`tar` 不在 PATH / 平台未发布)。
+**修复**:1) bridge 启动日志走 host stderr,Claude session `/mcp` 看 ccteam 启动报错 / Codex 看 server log;2) 走代理:在拉起 Claude/Codex 的 shell 里 `export HTTPS_PROXY=...`;3) 跳过 bridge 下载、走传统 system-wide 安装:`curl -sSL https://raw.githubusercontent.com/firstintent/ccteam/main/install.sh | sh`,然后**临时把 `.mcp.json` 的 command 改回 `ccteam` + args `["mcp-serve"]`** 直至 bridge 路径修复;4) 国内裸连慢首次卡住 → 镜像 GH Release 到内网,把 `index.js` 里的下载 URL 改成镜像。版本严格对齐 `.claude-plugin/plugin.json::version`(SoT);Bridge 通过 `binary --version` 输出与之比对,不匹配会重下。
+**相关**:A3 / A4。
+
+### A3c. plugin 装好但终端 `ccteam --version` 报 command not found
+**原因**:bridge 首次 MCP 调用会把 `${PLUGIN_ROOT}/bin/ccteam` symlink 到 `~/.local/bin/ccteam`,但如果 `~/.local/bin/` 不在 `$PATH`,终端找不到。
+**修复**:1) Claude/Codex 里先调一次 `mcp__ccteam__chat_list_bots` 触发 bridge 下载 + symlink;2) `echo $PATH | grep -q "$HOME/.local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc`(zsh 改 `~/.zshrc`)再 `source` 一次。bridge symlink 失败时会在 stderr 打印 hint,通常因 `~/.local/bin/` 不可写。
+**相关**:A3b。
 
 ### A4. `/mcp` 列表里没 `mcp__ct__*` 工具
 **原因**:MCP 没注册到 `.mcp.json` 或 `~/.claude.json`,或 plugin 装完没 reload。