cross-agent-teams-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jtianling
+
+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,296 @@
+# cross-agent-teams-mcp
+
+[中文说明](./README.zh-CN.md)
+
+An MCP daemon for cross-agent collaboration, with local delivery transports for tmux, Codex app-server, and Claude channel wake integration.
+
+## Quick Start
+
+The package ships two bins:
+
+- `cross-agent-teams-mcp` — the daemon (HTTP MCP server on `127.0.0.1:9100`).
+- `cross-agent-teams-channel` — a stdio MCP proxy that Claude Code talks to over stdio.  On startup it auto-bootstraps the daemon if no healthy daemon is reachable on the configured loopback URL.
+
+The recommended Claude Code MCP config collapses to a single stdio entry — no manual daemon startup needed:
+
+```jsonc
+{
+  "mcpServers": {
+    "cross-agent-teams": {
+      "command": "npx",
+      "args": ["-y", "-p", "cross-agent-teams-mcp", "cross-agent-teams-channel"]
+    }
+  }
+}
+```
+
+When the channel CLI starts and its configured daemon URL points at `127.0.0.1` / `localhost`, it probes `<daemon-url>/health`; if the daemon is not running, it spawns a detached daemon child (the same `cross-agent-teams-mcp` bin), waits up to 5s for `/health` to return 200, and only then opens its MCP client connection.  The auto-spawned daemon's stdout/stderr append to `~/.cross-agent-teams-mcp/daemon.log`.
+
+If the URL is non-loopback (e.g. `http://10.0.0.5:9100/mcp`), auto-spawn is disabled — the channel probes once and exits with a clear error if the daemon is unreachable.
+
+If you prefer explicit lifecycle control or are developing locally, you can still build and start the daemon manually:
+
+```bash
+pnpm build
+node dist/cli.js daemon --port 9100
+```
+
+The one-command local setup remains:
+
+```bash
+./start-server.sh
+```
+
+The script runs `pnpm build` first, then starts the background services.  To stop them:
+
+```bash
+./stop-server.sh
+```
+
+Logs and pid files are written into `logs/`.
+
+## Distribution
+
+This package publishes both `cross-agent-teams-mcp` (daemon) and `cross-agent-teams-channel` (Claude Code stdio proxy) bins from a single tarball.  The recommended configuration is the single-entry stdio form above; the auto-daemon bootstrap means most users never need to start the daemon manually.
+
+Developers who want explicit lifecycle control still have `start-server.sh` / `stop-server.sh` (and the manual `node dist/cli.js daemon --port 9100`).  Auto-daemon bootstrap is purely additive and does not change the daemon's HTTP API, MCP tool surface, or sqlite schema.
+
+### Breaking change: bin and package rename
+
+The previous workspace plugin `cross-agent-teams-channel` (which exposed a bin named `cross-agent-teams-proxy`) is removed.  Its code now lives inside `cross-agent-teams-mcp` as the `cross-agent-teams-channel` bin.  Any external MCP config that references the legacy `cross-agent-teams-proxy` bin or a hard-coded path under `plugins/cross-agent-teams-channel/dist/` must update to the unified single-bin form above.
+
+The HTTP `cross-agent-teams-mcp` MCP entry continues to work for users who prefer the explicit two-entry form.
+
+To run directly from source:
+
+```bash
+npx tsx src/cli.ts daemon --port 9100
+```
+
+By default the daemon listens on `127.0.0.1:9100`.  The MCP endpoint is `http://127.0.0.1:9100/mcp`, and the health check endpoint is `http://127.0.0.1:9100/health`.
+
+You can verify the service with:
+
+```bash
+curl http://127.0.0.1:9100/health
+```
+
+## Common Flags
+
+- `--port <port>`: listening port, default `9100`
+- `--token <token>`: enable Bearer token authentication
+- `--db <path>`: SQLite database path
+- `--pid-file <path>`: pid file path
+
+The default data directory is `~/.cross-agent-teams-mcp/`.  The default database file is `~/.cross-agent-teams-mcp/data.db`, and the default pid file is `~/.cross-agent-teams-mcp/daemon.pid`.
+
+If another instance is already running, startup returns `daemon already running pid=...`.
+
+## Delivery Transports
+
+The daemon currently supports these wake-up paths:
+
+- `tmux_pane_id`: inject text directly into a target tmux pane
+- `delivery.kind='codex-appserver'`: resume a Codex thread over websocket and start a turn
+- `delivery.kind='claude-channel'`: bind a Claude channel session and deliver channel wake notifications
+
+`register_agent(...)` now requires an explicit `client`.  Use one of `codex`, `claude-code`, or `opencode` for first-class runtimes.  For other agent harnesses, pass `client: "custom"` and optionally `client_name` for observability.
+
+When you do not explicitly choose a `team`, pass `project_dir` as the caller's current working directory.  The daemon derives the default team from that directory's basename, and still falls back to `"default"` when both fields are omitted.
+
+## Codex App-Server Delivery
+
+For daily Codex usage, the recommended entry point is `register_agent({ client: "codex", ... })`.  It registers a caller-supplied `thread_id` as a `codex-appserver` delivery target through the unified registration API.  It does not auto-bind a tmux pane.  If you want tmux fallback delivery, call `bind_runtime_identity(...)` after registration.
+
+`register_agent({ client: "codex", ... })` no longer guesses the caller's current thread from `thread/loaded/list`.  The daemon cannot safely infer "which loaded thread is mine" from the MCP session alone.  If `thread_id` is omitted, the tool returns `thread_id_required` with resumable thread ids for debugging instead of registering the wrong thread.
+
+Minimal example:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111"
+})
+```
+
+If you also want tmux fallback routing, bind runtime identity explicitly after registration:
+
+```text
+bind_runtime_identity({
+  agent: "codex",
+  ui_pid: 81979
+})
+```
+
+If you do not have the UI pid, you can fall back to `ui_tty + tmux_pane_id`:
+
+```text
+bind_runtime_identity({
+  agent: "codex",
+  ui_tty: "/dev/ttys026",
+  tmux_pane_id: "%1902"
+})
+```
+
+Override the websocket URL when needed:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111",
+  ws_url: "ws://127.0.0.1:8799"
+})
+```
+
+If the app-server requires a Bearer token, pass `auth_token_ref` as an environment variable name visible to the daemon:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111",
+  auth_token_ref: "CODEX_REMOTE_TOKEN"
+})
+```
+
+Behavior notes:
+
+- `register_agent({ client: "codex", ... })` is the recommended entry point
+- Default `ws_url` is `ws://127.0.0.1:8799`
+- `thread_id` is required for successful registration
+- tmux pane binding is handled separately by `bind_runtime_identity`
+- `detect_tmux_pane(...)` remains available for debugging, but does not write registry state
+- No loaded thread returns `no_loaded_threads`
+- Omitted `thread_id` returns `thread_id_required` with resumable thread ids for debugging
+- Success returns `{ agent_id, team, thread_id, ws_url }`
+
+Minimal Codex app-server startup:
+
+```bash
+codex app-server --listen ws://127.0.0.1:8799
+codex --remote ws://127.0.0.1:8799
+```
+
+You can also register a target manually with `register_agent`:
+
+```text
+register_agent({
+  model: "...",
+  name: "...",
+  role: "...",
+  team: "...",
+  delivery: {
+    kind: "codex-appserver",
+    thread_id: "11111111-1111-4111-8111-111111111111",
+    ws_url: "ws://127.0.0.1:8799"
+  }
+})
+```
+
+If the app-server requires a Bearer token:
+
+```text
+register_agent({
+  model: "...",
+  name: "...",
+  role: "...",
+  team: "...",
+  delivery: {
+    kind: "codex-appserver",
+    thread_id: "11111111-1111-4111-8111-111111111111",
+    ws_url: "ws://127.0.0.1:8799",
+    auth_token_ref: "CODEX_REMOTE_TOKEN"
+  }
+})
+```
+
+Behavior notes:
+
+- `thread_id` must be a UUID
+- `ws_url` must use `ws://` or `wss://`
+- `auth_token_ref` is interpreted only as an environment variable name
+- On success, `poke()` returns `{ ok: true, transport_used: 'codex-appserver', thread_id }`
+- On failure, `poke()` returns machine-readable errors such as `codex_connect_failed`, `codex_initialize_failed`, `codex_resume_failed`, `codex_turn_start_failed`, or `missing_auth_token`
+- When a target is explicitly registered as `codex-appserver`, the daemon does not fall back to tmux
+
+For a more complete Codex CLI setup example, see [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
+
+## Claude Code Channel Delivery
+
+For Claude Code sessions, prefer registering from the active MCP session with `register_claude_self(...)`.  If you do not explicitly choose a `team`, pass `project_dir` as the current working directory so the daemon derives the project team from its basename.
+
+```text
+register_claude_self({
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  channel_session_id: "csid-abc"
+})
+```
+
+You can also use the unified entry point:
+
+```text
+register_agent({
+  client: "claude-code",
+  model: "opus-4-7",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  channel_session_id: "csid-abc"
+})
+```
+
+For a more complete Claude Code setup example, see [docs/configs/claude-code.md](docs/configs/claude-code.md).
+
+## Using opencode with xats (tmux)
+
+opencode integrates with xats as a plain tmux-hosted TUI.  There is no dedicated launcher and no HTTP transport — pokes are delivered by pasting into the opencode pane via tmux, exactly the same path used for `client: "custom"`.
+
+Start opencode inside a tmux window, then register from within opencode's MCP session:
+
+```bash
+tmux new-window opencode
+```
+
+```text
+register_agent({
+  client: "opencode",
+  model: "opencode-default",
+  name: "my-opencode-agent",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  ui_pid: <opencode pid>
+})
+```
+
+Pass the opencode process pid as `ui_pid`.  The daemon resolves `pid → tty → tmux pane` and populates `tmux_pane_id` in the same registration call.  After registration, pokes from other agents route to the opencode pane as `transport_used: "tmux-poke"`.
+
+### Transport selection
+
+Transport selection is client-aware:
+
+- `client="claude-code"`: `claude-channel` first, then `tmux-poke`
+- `client="opencode"`: `tmux-poke`
+- `client="codex"`: `codex-appserver` first, then `tmux-poke`
+
+### Operator cutover
+
+If you are upgrading from a version that shipped the `opencode-server` transport:
+
+1. Stop the daemon with `./stop-server.sh` (this wipes `data.db` on purpose — the dropped `opencode_base_url` / `opencode_session_id` columns and the `opencode_pane_pre_registrations` table are not migrated).
+2. Rebuild: `pnpm build`.
+3. Restart with `./start-server.sh`.
+4. Remove any shell alias that pointed at `launch-opencode.sh` (the script no longer exists).
+5. Re-register opencode agents using the `register_agent({ client: "opencode", ui_pid, ... })` flow shown above.

package/README.zh-CN.md

@@ -0,0 +1,306 @@
+# cross-agent-teams-mcp
+
+[English README](./README.md)
+
+用于跨 agent 协作的 MCP daemon, 支持 tmux, Codex app-server 和 Claude channel wake 等本地投递方式.
+
+## 快速开始
+
+本包提供两个 bin:
+
+- `cross-agent-teams-mcp` — daemon (HTTP MCP server, 监听 `127.0.0.1:9100`).
+- `cross-agent-teams-channel` — Claude Code 用的 stdio MCP proxy.  启动时会自动 bootstrap daemon: 如果配置的 loopback URL 上没有健康的 daemon, 它会 spawn 一个 detached daemon 子进程, 等到 `/health` 返回 200 后再打开 MCP client。
+
+推荐的 Claude Code MCP config 折叠成单一 stdio entry, 不再需要手动起 daemon:
+
+```jsonc
+{
+  "mcpServers": {
+    "cross-agent-teams": {
+      "command": "npx",
+      "args": ["-y", "-p", "cross-agent-teams-mcp", "cross-agent-teams-channel"]
+    }
+  }
+}
+```
+
+channel CLI 启动时, 如果配置的 daemon URL 指向 `127.0.0.1` / `localhost`, 它会先去探测 `<daemon-url>/health`; 如果 daemon 没起来, 就 spawn 一个 detached daemon child (同一个 `cross-agent-teams-mcp` bin), 最多等 5 秒等 `/health` 返回 200, 之后再打开 MCP client.  自动起来的 daemon 的 stdout/stderr 会 append 到 `~/.cross-agent-teams-mcp/daemon.log`.
+
+如果 URL 不是 loopback (比如 `http://10.0.0.5:9100/mcp`), 自动 spawn 会被禁用 — channel 只探测一次, daemon 不可达就报错退出。
+
+如果你想显式控制 daemon 生命周期 (例如本地开发), 仍可以手动 build + 启动 daemon:
+
+```bash
+pnpm build
+node dist/cli.js daemon --port 9100
+```
+
+一键脚本仍然可用:
+
+```bash
+./start-server.sh
+```
+
+这个脚本会先执行 `pnpm build`, 然后再启动后台服务.  停止服务可以用:
+
+```bash
+./stop-server.sh
+```
+
+日志和 pid 文件会写到 `logs/` 目录.
+
+## 分发说明
+
+本包同时发布 `cross-agent-teams-mcp` (daemon) 和 `cross-agent-teams-channel` (Claude Code stdio proxy) 两个 bin, 来自同一个 tarball.  推荐使用上面的单 entry stdio 配置; 由于有 auto-daemon bootstrap, 大多数使用者不需要手动起 daemon。
+
+希望显式控制生命周期的开发者仍可以用 `start-server.sh` / `stop-server.sh` (或 `node dist/cli.js daemon --port 9100`).  Auto-daemon bootstrap 是纯增量行为, 不改变 daemon 的 HTTP API, MCP tool 表面或 sqlite schema。
+
+### Breaking change: bin 与 package 改名
+
+之前的 workspace plugin `cross-agent-teams-channel` (它暴露的 bin 名为 `cross-agent-teams-proxy`) 已删除.  代码合并进了 `cross-agent-teams-mcp`, 作为新的 `cross-agent-teams-channel` bin.  所有外部 MCP config 中引用旧 bin 名 `cross-agent-teams-proxy`, 或硬编码 `plugins/cross-agent-teams-channel/dist/` 路径的位置, 都需要改成上面的统一单 bin 形式。
+
+直接 HTTP 连接 `cross-agent-teams-mcp` 的 MCP entry 仍然可用, 适合喜欢显式两 entry 的用户。
+
+如果你想直接跑源码, 可以用:
+
+```bash
+npx tsx src/cli.ts daemon --port 9100
+```
+
+服务默认监听 `127.0.0.1:9100`.  MCP endpoint 是 `http://127.0.0.1:9100/mcp`, 健康检查地址是 `http://127.0.0.1:9100/health`.
+
+启动后可以用下面的命令确认服务正常:
+
+```bash
+curl http://127.0.0.1:9100/health
+```
+
+## 常用参数
+
+- `--port <port>`: 指定监听端口, 默认 `9100`
+- `--token <token>`: 开启 Bearer token 鉴权
+- `--db <path>`: 指定 SQLite 数据库路径
+- `--pid-file <path>`: 指定 pid 文件路径
+
+默认数据目录是 `~/.cross-agent-teams-mcp/`.  默认数据库文件是 `~/.cross-agent-teams-mcp/data.db`, 默认 pid 文件是 `~/.cross-agent-teams-mcp/daemon.pid`.
+
+如果已有实例在运行, 启动时会返回 `daemon already running pid=...`.
+
+## 投递方式
+
+当前 daemon 支持这些唤醒路径:
+
+- `tmux_pane_id`: 直接把文本注入目标 tmux pane
+- `delivery.kind='codex-appserver'`: 通过 websocket 恢复 Codex thread 并启动一轮 turn
+- `delivery.kind='claude-channel'`: 绑定 Claude channel session 并发送 channel wake 通知
+
+`register_agent(...)` 现在要求显式传 `client`.  一等运行时使用 `codex` / `claude-code` / `opencode`.  其它 agent harness 请传 `client: "custom"`, 并且可以选填 `client_name` 方便排查。
+
+如果同时传了 `ui_pid`, `client` 必须描述这个 `ui_pid` 背后的真实 runtime, 不是当前发起 MCP 调用的宿主。  例如, 在 Claude Code 里替 opencode pane 做注册时, 也要传 `client: "opencode"`。
+
+当用户没有显式指定 `team` 时, 调用方推荐传 `project_dir` 为当前工作目录.  daemon 会用该目录 basename 派生默认 team, 两者都不传时仍回落到 `"default"`.
+
+## Codex App-Server Delivery
+
+如果你平时主要在 Codex 里使用, 更推荐直接调用 `register_agent({ client: "codex", ... })`.  它会用调用者显式提供的 `thread_id` 把当前会话注册成 `codex-appserver` delivery, 同时保持统一入口.  它不会自动绑定 tmux pane.  如果你还需要 tmux 作为兜底唤醒路径, 请在注册成功后单独调用 `bind_runtime_identity(...)`.
+
+`register_agent({ client: "codex", ... })` 不再根据 `thread/loaded/list` 去猜“当前调用者自己的 thread”.  daemon 仅凭 MCP session 无法安全判断 loaded threads 里哪一个属于当前调用者.  如果省略 `thread_id`, 工具会返回 `thread_id_required`, 并附带可恢复的 thread id 列表供排查, 但不会继续注册.
+
+最简用法:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111"
+})
+```
+
+如果你还需要 tmux fallback delivery, 在注册后显式绑定 runtime identity:
+
+```text
+bind_runtime_identity({
+  agent: "codex",
+  ui_pid: 81979
+})
+```
+
+如果拿不到 UI pid, 可以退化到 `ui_tty + tmux_pane_id`:
+
+```text
+bind_runtime_identity({
+  agent: "codex",
+  ui_tty: "/dev/ttys026",
+  tmux_pane_id: "%1902"
+})
+```
+
+如果本地不是默认地址, 可以显式覆盖 `ws_url`:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111",
+  ws_url: "ws://127.0.0.1:8799"
+})
+```
+
+如果 app-server 开启了 Bearer token, 可以传 `auth_token_ref`, 它的值是 daemon 进程可见的环境变量名:
+
+```text
+register_agent({
+  client: "codex",
+  model: "gpt-5",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  thread_id: "11111111-1111-4111-8111-111111111111",
+  auth_token_ref: "CODEX_REMOTE_TOKEN"
+})
+```
+
+行为说明:
+
+- `register_agent({ client: "codex", ... })` 是新的推荐入口
+- 默认 `ws_url` 是 `ws://127.0.0.1:8799`
+- 成功注册必须显式提供 `thread_id`
+- tmux pane 绑定需要单独调用 `bind_runtime_identity(...)`
+- `bind_runtime_identity(...)` 的 `agent` 参数是必填, 用于选择内置进程匹配器
+- 优先使用 `ui_pid`, 也支持 `ui_tty + tmux_pane_id` 的降级校验路径
+- 没有 loaded thread 时返回 `no_loaded_threads`
+- 省略 `thread_id` 时返回 `thread_id_required`, 并附带可恢复 thread id 列表供排查
+- 成功时返回 `{ agent_id, team, thread_id, ws_url }`
+
+Codex app-server 的最小启动方式:
+
+```bash
+codex app-server --listen ws://127.0.0.1:8799
+codex --remote ws://127.0.0.1:8799
+```
+
+你也可以手动通过 `register_agent` 注册目标:
+
+```text
+register_agent({
+  model: "...",
+  name: "...",
+  role: "...",
+  team: "...",
+  delivery: {
+    kind: "codex-appserver",
+    thread_id: "11111111-1111-4111-8111-111111111111",
+    ws_url: "ws://127.0.0.1:8799"
+  }
+})
+```
+
+如果 app-server 开启了 Bearer token:
+
+```text
+register_agent({
+  model: "...",
+  name: "...",
+  role: "...",
+  team: "...",
+  delivery: {
+    kind: "codex-appserver",
+    thread_id: "11111111-1111-4111-8111-111111111111",
+    ws_url: "ws://127.0.0.1:8799",
+    auth_token_ref: "CODEX_REMOTE_TOKEN"
+  }
+})
+```
+
+行为说明:
+
+- `thread_id` 必须是 UUID
+- `ws_url` 只能使用 `ws://` 或 `wss://`
+- `auth_token_ref` 只会被解释为环境变量名
+- 成功时, `poke()` 返回 `{ ok: true, transport_used: 'codex-appserver', thread_id }`
+- 失败时, `poke()` 返回 machine-readable 错误, 例如 `codex_connect_failed`, `codex_initialize_failed`, `codex_resume_failed`, `codex_turn_start_failed`, `missing_auth_token`
+- 当目标显式注册为 `codex-appserver` 时, daemon 不会自动 fallback 到 tmux
+
+更完整的 Codex CLI 配置和启动示例见 [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
+
+## Claude Code Channel Delivery
+
+如果你平时主要在 Claude Code 里使用, 更推荐直接在当前 Claude 会话里调用 `register_claude_self(...)`.  这条 helper 会把注册写到当前 host session 上, 可以直接避免外部 `curl` 注册带来的 session 错位。  如果当前 host 已经知道 channel proxy 宣告的 `channel_session_id`, 可以这样完成自注册和 channel 绑定:
+
+```text
+register_claude_self({
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  channel_session_id: "csid-abc"
+})
+```
+
+如果你更想走统一入口, 也可以在当前 Claude 会话里直接调用 `register_agent({ client: "claude-code", ... })`:
+
+```text
+register_agent({
+  client: "claude-code",
+  model: "opus-4-7",
+  name: "lead",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  channel_session_id: "csid-abc"
+})
+```
+
+行为说明:
+
+- Claude Code 的 proxy session 不是 owner Claude session。  不要用外部 `curl` 代替当前 Claude 会话做注册, 否则后续工具调用仍然可能看到 `unknown_agent`
+- `register_claude_self(...)` 是 Claude Code 的首选路径, 因为它天然运行在当前 session 上
+- `client="claude-code"` 时, `poke` 会优先走 `claude-channel`, 失败后再回退到 `tmux`
+- 如果注册响应里仍然带 `hint`, 说明 tmux fallback 还没有完成绑定, 这时调用 `bind_runtime_identity(...)`
+- `bind_channel(...)` 仍然保留, 但它只是低层重绑工具, 适合已注册 row 在 proxy 切换到新 `channel_session_id` 后补绑
+
+更完整的 Claude Code 配置见 [docs/configs/claude-code.md](docs/configs/claude-code.md).
+
+## 在 tmux 里使用 opencode
+
+opencode 以普通 tmux TUI 的形式接入 xats, 不再提供专用 launcher, 也不再走 HTTP 专用 transport.  投递方式和 `client: "custom"` 完全一致: 由 daemon 将文本粘贴到 opencode 所在 tmux pane.
+
+在 tmux 窗口里启动 opencode, 然后在 opencode 自己的 MCP session 里注册:
+
+```bash
+tmux new-window opencode
+```
+
+```text
+register_agent({
+  client: "opencode",
+  model: "opencode-default",
+  name: "my-opencode-agent",
+  project_dir: "/Users/me/workspace/cross-agent-teams-mcp",
+  role: "worker",
+  ui_pid: <opencode 进程 pid>
+})
+```
+
+把 opencode 进程 pid 作为 `ui_pid` 传入, daemon 会在这次注册里走 `pid → tty → tmux pane` 的链路完成 `tmux_pane_id` 绑定.  其它 agent 对此 agent 的 `poke` 统一走 `transport_used: "tmux-poke"`.
+
+行为说明:
+
+- `client="opencode"` 时, `poke` 走 `tmux-poke`
+- 如果注册响应里仍然带 `hint`, 说明 tmux fallback 还没有完成绑定, 这时调用 `bind_runtime_identity(...)`
+
+### 运维 cutover
+
+如果你从带 `opencode-server` 专用 transport 的旧版本升级:
+
+1. 用 `./stop-server.sh` 停掉 daemon (会顺便清空 `data.db`; 被删除的 `opencode_base_url` / `opencode_session_id` 列和 `opencode_pane_pre_registrations` 表并不做迁移)
+2. `pnpm build` 重新构建
+3. `./start-server.sh` 启动新版 daemon
+4. 删掉任何指向 `launch-opencode.sh` 的 shell alias (脚本已经不存在)
+5. 按上面的 `register_agent({ client: "opencode", ui_pid, ... })` 重新注册 opencode agent
+
+更完整的 opencode 配置见 [docs/configs/opencode.md](docs/configs/opencode.md).

package/dist/channel-cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+interface CliArgs {
+    daemonUrl: string;
+}
+declare class CliArgError extends Error {
+    constructor(message: string);
+}
+declare function buildStartupHint(csid: string): {
+    content: string;
+    meta: {
+        source: string;
+        kind: string;
+    };
+};
+declare function parseCliArgs(argv: readonly string[], env?: NodeJS.ProcessEnv): CliArgs;
+declare function main(argv?: readonly string[], env?: NodeJS.ProcessEnv): Promise<void>;
+
+export { CliArgError, buildStartupHint, main, parseCliArgs };