cross-agent-teams-mcp 0.5.3 → 0.5.5

package/README.md

@@ -4,12 +4,47 @@
 
 A local MCP daemon that lets multiple AI coding agents (Claude Code, Codex, opencode) running on the same machine talk to each other.  Agents register, send 1-to-1 messages, broadcast to a team or role, and wake each other up — all over a single daemon, no external services.
 
-## What's in the npm package
+## Quick start
 
-`cross-agent-teams-mcp` ships two bins from the same package:
+### Claude Code
 
-- **`cross-agent-teams-mcp daemon`** — the long-running HTTP daemon.  Stores agents, mailboxes, and the task list in a local SQLite file, exposes its tools at `http://127.0.0.1:9100/mcp`.
-- **`cross-agent-teams-channel`** — a stdio MCP shim that lets Claude Code receive `notifications/channel_wake` from the daemon (Claude Code's experimental channel capability).  Required for Claude Code wake-ups; not needed for Codex (which uses its own app-server transport) or opencode (which falls back to tmux-pane injection).
+```bash
+# 1. Start the daemon (run once, keep it alive)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. In your project, install the MCP config
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
+
+# 3. Start Claude Code with the channel loader (manual permission prompt expected)
+claude --dangerously-load-development-channels server:cross-agent-teams-channel
+```
+
+### Other agents (Codex, opencode, ...)
+
+```bash
+# 1. Start the daemon (run once, keep it alive)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. In your project, install the MCP config (interactive picker)
+npx mcpsmgr add jtianling/cross-agent-teams-mcp
+
+# 3. Start your coding agent as usual
+```
+
+Note: only Claude Code gets push wake out of the box.  Codex needs the `--remote` + launcher setup (see section 2 below) for pokes; without it, it has a mailbox but no wake.  opencode / cursor / other agents only receive pokes when running inside a tmux pane.  If push wake isn't wired up, ask the agent to check its inbox manually ("check my xats inbox").
+
+Then talk to your agent in plain language:
+
+```
+# In agent A:
+Register me to xats as backend on team default.
+
+# In agent B:
+Register me to xats as frontend on team default.
+Send backend a message: the API has changed.
+```
+
+That's it.  Sections below cover the details — daemon flags, manual MCP config, codex `--remote` setup, more usage patterns.
 
 ## 1. Start the daemon
 
@@ -30,7 +65,21 @@ Common flags:
 
 ## 2. Configure your agent's MCP client
 
-### Claude Code (needs both entries — HTTP for tools, stdio for channel wake)
+### Recommended: `mcpsmgr` (shown in Quick start)
+
+[`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) reads this repo's `mcpsmgr.json` and writes the right MCP entries into your agent's config in one shot — including the Claude Code stdio channel proxy entry, the Codex `experimental_use_rmcp_client` toggle, and the streamable-http MCP entry.
+
+To override the daemon port:
+
+```bash
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code --port 9300
+```
+
+### Manual config
+
+If you don't want `mcpsmgr` (private fork, custom token, custom stdio args, or you just prefer hand-edited config), the raw per-agent configs are below.
+
+#### Claude Code (needs both entries — HTTP for tools, stdio for channel wake)
 
 `.mcp.json` (or `~/.claude.json`):
 
@@ -64,32 +113,92 @@ claude --dangerously-load-development-channels server:cross-agent-teams-channel
 
 The `server:<name>` suffix MUST equal the MCP server key in `.mcp.json` (`cross-agent-teams-channel` above).  If your daemon uses `--token <t>`, add `"headers": { "Authorization": "Bearer <t>" }` to the HTTP entry.
 
-### Codex CLI
+#### Codex CLI
+
+Codex talks to the daemon over Streamable HTTP.  Wake-ups go through Codex's own app-server WebSocket transport — there is no channel proxy involved.
 
-Codex talks to the daemon directly over Streamable HTTP.  No channel proxy is needed — Codex has no `claude/channel` capability, and wake-ups are delivered via Codex's own app-server websocket transport (or tmux paste fallback).
+##### Minimum config (mailbox only, no push wake)
 
 `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.cross-agent-teams]
+experimental_use_rmcp_client = true
+
+[mcp_servers.cross-agent-teams-mcp]
 type = "streamable-http"
 url = "http://127.0.0.1:9100/mcp"
 ```
 
-(daemon with `--token <t>`: add `[mcp_servers.cross-agent-teams.headers]` and `Authorization = "Bearer <t>"`.)
+`experimental_use_rmcp_client = true` MUST sit at the top level — without it, streamable-http MCP servers fail to load.
+
+(With `--token <t>` on the daemon: add `[mcp_servers.cross-agent-teams-mcp.headers]` and `Authorization = "Bearer <t>"`.)
 
-If you want other agents to be able to **wake** this Codex thread (not only mail it), start Codex's app-server alongside Codex itself:
+In this minimum mode, `send_message` to this Codex still drops a row in its mailbox, but you have to call `get_inbox` yourself to read it — no push wake.
+
+##### Let other agents wake you (codex-appserver poke)
+
+To let other agents **wake** this Codex thread (not just mail it), you need `codex-appserver` delivery.  The setup has one non-obvious gotcha worth calling out:
+
+> **In `codex --remote` mode, MCP servers are loaded by the app-server, NOT by the TUI.**  The MCP entry above must therefore live in the `CODEX_HOME` that the **app-server** reads at startup — usually the global `~/.codex/config.toml`.  Setting `CODEX_HOME` on the TUI alone does nothing for MCP under `--remote`.
+
+Start order:
 
 ```bash
-codex app-server --listen ws://127.0.0.1:8799     # in one terminal
-codex --remote ws://127.0.0.1:8799                # in another terminal (TUI)
+# 1) Long-lived codex app-server somewhere (its CODEX_HOME decides the MCP set).
+codex app-server --listen ws://127.0.0.1:8799
+
+# 2) Codex TUI in a separate terminal, connected to the same app-server.
+codex --remote ws://127.0.0.1:8799
 ```
 
-Without an app-server, `send_message` to this Codex still queues a mailbox row, but you have to call `get_inbox` yourself to read it — there is no push to wake the thread.
+If the app-server's `CODEX_HOME` doesn't have `cross-agent-teams-mcp` configured, the codex agent inside `--remote` won't see the MCP tools at all and `register_agent` will never fire.
+
+##### Recommended: launcher with tmux pane auto-bind
+
+For pokes to be injected directly into the running Codex thread (rather than landing as a tmux paste), the daemon needs to know which tmux pane the codex process lives in.  The launcher pre-claims a pane via the `pre-register-codex-pane` CLI before exec'ing codex.  Add to `~/.zshrc`:
+
+```zsh
+free-xats-codex() {
+    local xats_agent_id codex_home search_dir
+    xats_agent_id="$(uuidgen)"
+    search_dir="$PWD"
+    while [[ "$search_dir" != "/" ]]; do
+        if [[ -f "$search_dir/.codex/config.toml" ]]; then
+            codex_home="$search_dir/.codex"
+            break
+        fi
+        search_dir="${search_dir:h}"
+    done
+
+    if [[ -n "$TMUX_PANE" ]]; then
+        npx -y cross-agent-teams-mcp pre-register-codex-pane \
+            --pane "$TMUX_PANE" \
+            --agent-id "$xats_agent_id" \
+            >/dev/null 2>&1 \
+            || echo "[xats] pre-register failed (continuing without pane claim)" >&2
+    fi
+
+    if [[ -n "$codex_home" ]]; then
+        CODEX_HOME="$codex_home" exec codex \
+            --remote ws://127.0.0.1:8799 \
+            -c xats.agent_id="\"$xats_agent_id\"" "$@"
+    else
+        exec codex \
+            --remote ws://127.0.0.1:8799 \
+            -c xats.agent_id="\"$xats_agent_id\"" "$@"
+    fi
+}
+```
+
+What the launcher does:
+
+- Inside tmux (`$TMUX_PANE` set): pre-registers the pane → uuid mapping with the daemon (120s TTL).  When the codex agent later calls `register_agent({agent_type: "codex", thread_id: $CODEX_THREAD_ID, ...})`, the daemon resolves `tmux_pane_id` automatically by matching the pre-reg against the codex argv.
+- `--remote ws://127.0.0.1:8799` connects to the long-lived app-server from step (1) above.
+- `-c xats.agent_id="\"$uuid\""` exposes the uuid in codex's argv so the daemon can verify the pane.
 
-Detailed config (auth headers, tmux fallback, lower-level `register_agent` form): [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
+More detail (auth headers, lower-level `register_agent` form): [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
 
-### Other coding agents (opencode, cursor, ...)
+#### Other coding agents (opencode, cursor, ...)
 
 Anything that is not Claude Code or Codex — opencode, cursor, an editor extension, your own harness — connects over plain Streamable HTTP and registers as `agent_type="custom"` (the agent figures this out for you).  There is no dedicated wake-up transport for these; cross-agent pokes are delivered by injecting text into the agent's tmux pane, so run the agent inside a tmux window and the daemon will resolve `pid → tty → pane` automatically when you register.
 

package/README.zh-CN.md

@@ -4,12 +4,47 @@
 
 一个本地 MCP daemon, 让同一台机器上的多个 AI 编码 agent (Claude Code, Codex, opencode) 互相通信.  agent 注册到 daemon, 互发 1-to-1 消息, 在 team 或 role 内广播, 互相唤醒 — 全部通过一个本地 daemon 完成, 不依赖任何外部服务.
 
-## npm 包内容
+## 快速开始
 
-`cross-agent-teams-mcp` 在同一个包里发两个 bin:
+### Claude Code
 
-- **`cross-agent-teams-mcp daemon`** — 长驻 HTTP daemon.  把 agent 注册表和邮箱存在本地 SQLite 文件里, MCP endpoint 在 `http://127.0.0.1:9100/mcp`.
-- **`cross-agent-teams-channel`** — stdio MCP shim, 让 Claude Code 通过 `notifications/channel_wake` 接收唤醒通知 (Claude Code 的 experimental channel capability).  Claude Code 需要它接收 wake; Codex 用自己的 app-server 通道, opencode 走 tmux-pane 文本注入, 都不需要 channel proxy.
+```bash
+# 1. 启动 daemon (跑一次, 保持运行)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. 在你的项目下安装 MCP 配置
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
+
+# 3. 带上 channel loader 启动 Claude Code (需要手动确认权限)
+claude --dangerously-load-development-channels server:cross-agent-teams-channel
+```
+
+### 其它 agent (Codex, opencode, ...)
+
+```bash
+# 1. 启动 daemon (跑一次, 保持运行)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. 在你的项目下安装 MCP 配置 (交互式选择对应 agent)
+npx mcpsmgr add jtianling/cross-agent-teams-mcp
+
+# 3. 按平时的方式启动对应 coding agent
+```
+
+注意: 只有 Claude Code 默认就能收到 push 唤醒.  Codex 需要 `--remote` + launcher 配置 (见下面 section 2) 才能被 poke; 没配的话只有邮箱, 不会自动醒.  opencode / cursor 等其它 agent 只有跑在 tmux pane 里才能被 poke.  没接通 push 唤醒的情况下, 让 agent 自己手动收信即可 (跟它说"查一下我的 xats inbox").
+
+之后用平时跟 agent 对话的语言就能用了:
+
+```
+# Agent A 里:
+Register me to xats as backend on team default.
+
+# Agent B 里:
+Register me to xats as frontend on team default.
+Send backend a message: the API has changed.
+```
+
+就这些.  下面是细节 — daemon 参数, 手动 MCP 配置, codex `--remote` 设置, 更多使用方式.
 
 ## 1. 启动 daemon
 
@@ -30,7 +65,21 @@ daemon 默认监听 `127.0.0.1:9100`.  MCP endpoint: `http://127.0.0.1:9100/mcp`
 
 ## 2. 在 agent 端配置 MCP client
 
-### Claude Code (两个条目都需要 — HTTP 用于工具, stdio 用于 channel 唤醒)
+### 推荐: `mcpsmgr` (快速开始里已经演示)
+
+[`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) 读取本仓库的 `mcpsmgr.json`, 一次性把对应 agent 需要的 MCP 条目写进配置 — 包括 Claude Code 的 stdio channel proxy 条目, Codex 的 `experimental_use_rmcp_client` 开关和 streamable-http MCP 条目.
+
+覆盖 daemon 端口:
+
+```bash
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code --port 9300
+```
+
+### 手动配置
+
+如果不想用 `mcpsmgr` (私有 fork / 自定义 token / 自定义 stdio args / 或者就是想手写), 各 agent 的原始配置如下.
+
+#### Claude Code (两个条目都需要 — HTTP 用于工具, stdio 用于 channel 唤醒)
 
 `.mcp.json` (或 `~/.claude.json`):
 
@@ -64,32 +113,92 @@ claude --dangerously-load-development-channels server:cross-agent-teams-channel
 
 `server:<name>` 后缀 **必须** 等于 `.mcp.json` 里的 MCP server key (上例中是 `cross-agent-teams-channel`).  如果 daemon 启动带了 `--token <t>`, 在 HTTP 条目里加 `"headers": { "Authorization": "Bearer <t>" }`.
 
-### Codex CLI
+#### Codex CLI
+
+Codex 通过 Streamable HTTP 跟 daemon 通信.  唤醒走 Codex 自己的 app-server WebSocket, 不经 channel proxy.
 
-Codex 直接通过 Streamable HTTP 跟 daemon 通信, 不需要 channel proxy — Codex 没有 `claude/channel` capability, 唤醒走 Codex 自己的 app-server websocket (或 tmux paste 兜底).
+##### 最小配置 (只能收邮箱, 没有 push 唤醒)
 
 `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.cross-agent-teams]
+experimental_use_rmcp_client = true
+
+[mcp_servers.cross-agent-teams-mcp]
 type = "streamable-http"
 url = "http://127.0.0.1:9100/mcp"
 ```
 
-(daemon 带了 `--token <t>` 时, 加 `[mcp_servers.cross-agent-teams.headers]` 和 `Authorization = "Bearer <t>"`.)
+`experimental_use_rmcp_client = true` 必须放在**顶级**, 缺这条 streamable-http MCP 加载不了.
+
+(daemon 带了 `--token <t>` 时, 加 `[mcp_servers.cross-agent-teams-mcp.headers]` 和 `Authorization = "Bearer <t>"`.)
 
-如果你希望别的 agent 能**唤醒**这个 Codex thread (不只是给它发邮件), 在跑 Codex 之前把 codex app-server 一起拉起来:
+这种最小配置下 `send_message` 给这个 codex 会写邮箱, 但需要手动调 `get_inbox` 拉读, 没有跨会话 push 唤醒.
+
+##### 让别人能唤醒你 (codex-appserver poke)
+
+要让别的 agent 能**主动唤醒**这个 codex thread (而不只是发邮件), 需要 `codex-appserver` delivery.  这里有个不直观的坑要写清楚:
+
+> **`codex --remote` 模式下, MCP server 是 app-server 加载的, 不是 TUI 加载的**.  上面那段 MCP 配置必须放在 **app-server** 启动时读到的 `CODEX_HOME` 里 — 一般就是全局 `~/.codex/config.toml`.  仅在 TUI 这边设 `CODEX_HOME` 在 `--remote` 模式下对 MCP 不起作用.
+
+启动顺序:
 
 ```bash
-codex app-server --listen ws://127.0.0.1:8799     # 一个终端
-codex --remote ws://127.0.0.1:8799                # 另一个终端 (TUI)
+# 1) 在某个长跑终端起 codex app-server (它的 CODEX_HOME 决定 MCP set)
+codex app-server --listen ws://127.0.0.1:8799
+
+# 2) 在另一个终端启动 codex TUI, 连同一个 app-server
+codex --remote ws://127.0.0.1:8799
 ```
 
-不启 app-server 也能用 — `send_message` 给这个 Codex 仍然会写到邮箱, 但需要你自己调 `get_inbox` 拉读, 没有推送唤醒.
+如果第 1 步的 app-server 的 `CODEX_HOME` 里没配 `cross-agent-teams-mcp`, `--remote` 进去的 codex agent 根本看不到 MCP 工具, `register_agent` 调都调不到.
+
+##### 推荐: launcher 函数 (tmux pane 自动绑定)
+
+为了让 daemon 把 wake-hint 直接 inject 到 codex thread (而不是只 paste 到 tmux pane), daemon 需要知道 codex 进程在哪个 tmux pane.  launcher 通过 `pre-register-codex-pane` CLI 在 exec codex 之前先把 pane 占住.  把下面的函数加到 `~/.zshrc`:
+
+```zsh
+free-xats-codex() {
+    local xats_agent_id codex_home search_dir
+    xats_agent_id="$(uuidgen)"
+    search_dir="$PWD"
+    while [[ "$search_dir" != "/" ]]; do
+        if [[ -f "$search_dir/.codex/config.toml" ]]; then
+            codex_home="$search_dir/.codex"
+            break
+        fi
+        search_dir="${search_dir:h}"
+    done
+
+    if [[ -n "$TMUX_PANE" ]]; then
+        npx -y cross-agent-teams-mcp pre-register-codex-pane \
+            --pane "$TMUX_PANE" \
+            --agent-id "$xats_agent_id" \
+            >/dev/null 2>&1 \
+            || echo "[xats] pre-register failed (continuing without pane claim)" >&2
+    fi
+
+    if [[ -n "$codex_home" ]]; then
+        CODEX_HOME="$codex_home" exec codex \
+            --remote ws://127.0.0.1:8799 \
+            -c xats.agent_id="\"$xats_agent_id\"" "$@"
+    else
+        exec codex \
+            --remote ws://127.0.0.1:8799 \
+            -c xats.agent_id="\"$xats_agent_id\"" "$@"
+    fi
+}
+```
+
+行为:
+
+- tmux 内 (`$TMUX_PANE` 非空): 先发一条 pre-register (pane_id + UUID + 120s TTL) 给 daemon.  codex agent 之后调 `register_agent({agent_type: "codex", thread_id: $CODEX_THREAD_ID, ...})` 时, daemon 会用 pending pre-reg + 匹配 codex 进程 argv 自动绑 `tmux_pane_id`.
+- `--remote ws://127.0.0.1:8799` 让 codex 连步骤 (1) 起好的 app-server.
+- `-c xats.agent_id="\"$uuid\""` 把 UUID 暴露在 codex argv 里, daemon 用它反向校验 pane.
 
-详细配置 (auth header, tmux fallback, 底层 `register_agent` 用法): [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
+详细配置 (auth header, 底层 `register_agent` 用法): [docs/configs/codex-cli.md](docs/configs/codex-cli.md).
 
-### 其它编码 agent (opencode, cursor, ...)
+#### 其它编码 agent (opencode, cursor, ...)
 
 非 Claude Code 也非 Codex 的工具 — opencode, cursor, 编辑器扩展, 自己的 harness — 直接通过 Streamable HTTP 连 daemon, 注册时用 `agent_type="custom"` (agent 自己会判断).  这些 agent 没有专用的唤醒通道; 跨 agent poke 通过把文本注入到 agent 所在的 tmux pane 实现, 所以把 agent 跑在 tmux 窗口里, 注册时 daemon 会自动解析 `pid → tty → pane`.
 

package/dist/cli.js

@@ -388,6 +388,7 @@ function toAgentRow(row) {
 var AgentsRepo = class {
   constructor(db) {
     this.db = db;
+    this.list = this.list.bind(this);
   }
   db;
   findByIdentity(args) {
@@ -525,8 +526,8 @@ var AgentsRepo = class {
     );
   }
   list(args) {
-    const rows = this.db.prepare(
-      `SELECT
+    const exclude = args.excludeRoles ?? [];
+    const baseSelect = `SELECT
          agent_id,
          agent_type,
          agent_type_name,
@@ -539,9 +540,17 @@ var AgentsRepo = class {
          delivery_payload,
          last_seen_at
        FROM agents
-       WHERE team=?
-       ORDER BY registered_at ASC`
-    ).all(args.team);
+       WHERE team=?`;
+    const orderBy = ` ORDER BY registered_at ASC`;
+    let rows;
+    if (exclude.length > 0) {
+      const placeholders = exclude.map(() => "?").join(",");
+      rows = this.db.prepare(
+        `${baseSelect} AND role NOT IN (${placeholders})${orderBy}`
+      ).all(args.team, ...exclude);
+    } else {
+      rows = this.db.prepare(`${baseSelect}${orderBy}`).all(args.team);
+    }
     const nowMs = Date.now();
     return rows.map((row) => {
       const agent = toAgentRow(row);
@@ -3642,7 +3651,7 @@ function registerBusinessTools(server, db, getCallerAgentId, fanout, onRegisterS
       if (typeof who !== "string") return toText(who);
       const row = agents.findById(who);
       return run(() => ({
-        agents: agents.list({ team: row.team }).map(toPublicAgentRow)
+        agents: agents.list({ team: row.team, excludeRoles: ["__channel_proxy__"] }).map(toPublicAgentRow)
       }));
     }
   );
@@ -4249,11 +4258,24 @@ function runCleanup(db, opts = {}) {
   );
   const deleteMessages = db.prepare(`DELETE FROM messages WHERE sent_at < ?`);
   const deleteEvents = db.prepare(`DELETE FROM events WHERE created_at < ?`);
+  const deleteStaleProxies = db.prepare(
+    `DELETE FROM agents
+      WHERE role = '__channel_proxy__'
+        AND last_seen_at < ?
+        AND NOT EXISTS (
+          SELECT 1 FROM agents host
+          WHERE host.delivery_kind = 'claude-channel'
+            AND host.role <> '__channel_proxy__'
+            AND json_extract(host.delivery_payload, '$.channel_session_id')
+                = json_extract(agents.delivery_payload, '$.channel_session_id')
+        )`
+  );
   const tx = db.transaction(() => {
     const s = deleteStatus.run(ageCutoff);
     const m = deleteMessages.run(ageCutoff);
     const e = deleteEvents.run(ageCutoff);
-    return Number(s.changes) + Number(m.changes) + Number(e.changes);
+    const p = deleteStaleProxies.run(ageCutoff);
+    return Number(s.changes) + Number(m.changes) + Number(e.changes) + Number(p.changes);
   });
   return { deleted: tx() };
 }