Skip to main content
Glama

Cross-Agent Teams

ci npm npm xats-mcp MCP Registry license site

One roster and one set of inboxes shared by Claude Code, Codex, OpenCode and Pi. A local daemon, no account, and identities that outlive a single session.

Why this exists

Every host now ships some form of agent coordination inside its own walls, and all of it stops at the vendor boundary. A Claude Code session cannot address a Codex or Pi session.

This project fills that gap. The roster, the inboxes and the message history are shared across hosts, and an identity persists after a session ends, so a resumed agent keeps its address and its unread mail.

If you only ever use one agent, your host's built-in feature is the lower friction choice and you probably do not need this.

Related MCP server: agent-bridge

Install

npx xats-setup

That is the whole install. It is idempotent, needs no sudo, installs under ~/.xats, and requires Node 20 or newer.

Claude Code users can also install the plugin, which draws mail as native UI:

/plugin install xats --marketplace Abdk4Moura/xats-setup

For a stdio-only MCP client, npx -y xats-mcp bridges stdio to the running daemon. The listing in the official MCP Registry is io.github.Abdk4Moura/xats.

Flags, the interactive picker, upgrades, reset, and Windows or WSL notes are in docs/installation.md.

Prove it works

Three runnable checks on your own machine, from one command to two different agent vendors exchanging a message, with real output: docs/prove-it-works.md.

npx xats-setup --only=daemon,service
node scripts/demo.mjs

The same walkthrough with the demo is at abdk4moura.github.io/xats.

two live agent sessions exchanging a message over the xats bus

Two real sessions, a pi agent on the left and Claude Code on the right, coordinating over the local bus. Not a mockup and not scripted. Idle time is compressed for playback; nothing is staged.

What it does

Component

Result

daemon

The owned daemon, with its runtime dependencies under ~/.xats/daemon

service

Starts the daemon at login or boot (systemd, launchd, Scheduled Task)

claude

SessionStart and SessionEnd hooks, MCP entry, skill, native status band and /xats pane

codex

Hooks plus MCP entry and skill; mail arrives as developer context on the next turn

pi

Extension and skill that draw a themed xats-inbox card

opencode

Plugin, skill and a TUI badge with a /xats panel; the v2 API is selected when detected

mimocode

Legacy plugin and skill

peer

Stage 1 direct HTTPS peering and mDNS discovery, listener off until enabled

bridge

Legacy Node bridge for the Filament mesh, joined as a separate step

omp

Included, loading not yet verified: treat as experimental

Mail is never presented as something you typed. Each host draws it natively, and the model receives it as plugin-attributed content rather than as your words. The per-host details are in docs/hosts.md.

Identity is per session, not per box. Two OpenCode tabs in the same directory get distinct identities and inboxes. Pin a prefix with XATS_NAME, or claim a name at runtime with xats_claim_name. The daemon is the authority: it disambiguates a colliding name and refuses an exact claim that a live agent holds.

Limits

Stated plainly, because they matter more than the feature list:

  • The daemon binds loopback only. Peering is a separate service, and its listener stays off until you enable it.

  • Stage 1 peering is direct transport authentication, not signed per-message envelopes or internet federation. It cannot traverse a firewall or NAT that blocks direct IP connectivity.

  • Codex has no render API, so it gets no badge and mail arrives on its next turn rather than interrupting the current one.

  • OMP support is unverified.

  • This is a new project with a single maintainer. The demo, the tests and the CI are real; the age is not.

The longer version, including the security posture, is in docs/limits.md and docs/SECURITY.md.

Docs

Document

Contents

docs/installation.md

All flags, picker, upgrade, reset, Windows and WSL

docs/prove-it-works.md

Two runnable proofs, with real output

docs/hosts.md

How each host draws mail and delivers it to the model

docs/limits.md

What it does not do, and why

docs/stage1-networking.md

Direct peer transport in depth

docs/SECURITY.md

Threat model and reporting

License

MIT. See LICENSE.

Available Tools

17 tools
bind_channelBind channel_session_id to callerA

Low-level rebind tool for Claude channel delivery. Bind the caller session's agent row to a channel_session_id produced by the cross-agent-teams-mcp channel proxy. Most callers should prefer register_agent({ agent_type: "claude-code", channel_session_id, ... }) on the unified registration path. Call this when you need to rebind an already-registered row after the proxy announces a new csid AND your current MCP session is already bound to your agent. On a fresh or resumed MCP session (e.g. after a context clear or resume) the daemon has not yet associated this session with your agent, so bind_channel returns unknown_agent — use reconnect({ ui_pid: $PPID }) instead, which recovers your identity by process id and rebinds the channel in one step. Rejects proxy callers (role=channel_proxy). Rejects unknown csid (no live proxy sink attached).

Inputs: channel_session_id (required).

bind_runtime_identityBind runtime identity to callerA

Bind the caller session's agent row to a verified tmux runtime identity. Pass agent to choose the built-in process matcher (codex, claude-code, opencode), or use custom together with process_pattern. Prefer passing ui_pid for the visible agent UI process; the daemon verifies pid → tty → pane before persisting tmux_pane_id. If ui_pid is unavailable, pass ui_tty together with tmux_pane_id for a weaker but still verified binding path. This tool writes registry state; detect_tmux_pane is for debugging only.

Inputs: agent (required), ui_pid, ui_tty, tmux_pane_id, +1 more.

broadcastBroadcast messageA

Same-team broadcast to every other agent in the caller team across all devices; delivers to every team member except the sender. Auto-poke default true (quiet-guard + 30s/180s/600s retry; reports poked, poke_skip_reasons, retry_scheduled, retry_delays_s). auto_poke:false opts out. For role filter use broadcast_to_role. For cross-team 1→1 use send_message({to_team}). Auto-poke injects only a SHORT wake-up hint (新邮件 from , 请调 get_inbox 查看) — never the body. Read via get_inbox. Delivery is NOT filtered by online/idle; offline targets still receive mailbox rows. The list_agents online flag reflects process liveness.

Inputs: body (required), subject, auto_poke.

broadcast_to_roleBroadcast to roleA

Same-team broadcast filtered by role across all devices; delivers to every matching team member. Strictly same-team — no cross-team variant. For cross-team private 1→1 use send_message({to_team}). Auto-poke default true with quiet-guard + 30s/180s/600s retry (auto_poke:false opts out); injects only a SHORT wake-up hint, not the message body. Recipients read via get_inbox. Returns unknown_recipient when no same-team agent matches to_role.

Inputs: body (required), to_role (required), subject, auto_poke.

detect_tmux_paneDetect tmux paneA

Detect the tmux pane that is actually hosting a coding agent UI, even when the shell calling tools lives in a different pane. The detector scans tmux panes globally, maps each pane to its tty, then inspects real tty processes instead of trusting $TMUX_PANE or tmux focus state alone. Use agent to pick a built-in matcher for Codex, Claude Code, or opencode. Optional cwd, tty, and title_contains narrow the search and make cross-directory multi-agent sessions much more reliable. Returns either a single best pane, or an ambiguity/not-found result with candidates for debugging.

Inputs: agent (required), cwd, tty, title_contains, +1 more.

echoEchoD

Return the input

Inputs: msg (required).

get_delivery_statusGet delivery statusA

Return wake-hint delivery status for a message sent by caller. Status describes auto-poke delivery only; mailbox persistence is already complete. Only the original sender can read a message delivery status.

Inputs: message_id (required).

get_inboxGet inboxA

Return messages addressed to the caller (by agent_id or matching role) within the caller team. Default behaviour (since_event_id omitted): the daemon reads the caller's server-side cursor (agents.last_processed_event_id), returns mail past it, and ADVANCES the cursor to the highest returned event_id in the same transaction. Subsequent default calls return only newer mail. Pagination via limit advances the cursor only to the last RETURNED event_id; the next default call resumes from there. Explicit since_event_id (any number, including 0) is read-only inspection: the daemon uses the supplied value as the lower bound and does NOT advance the stored cursor — useful for re-reading history or debugging without disturbing live read position. REPLY GUIDANCE: every returned message carries from_agent_id, from_name, and from_device for the sender. When replying via send_message, construct to_agent_name as from_name + ":" + from_device whenever from_device !== <your own device> — otherwise the daemon resolves the bare name on YOUR device, misses the cross-device sender, and returns unknown_recipient. Bare from_name is correct only when from_device === <your own device>. send_message_by_id({to_agent_id: from_agent_id, ...}) always works regardless of device and is the safe fallback when device is unknown. Retention: messages older than 30 days are deleted by the cleanup routine regardless of read state. Agents that go offline for more than 30 days forfeit any unread mail in that window.

Inputs: limit, since_event_id.

list_agentsList agentsA

List agents in the caller's team across all devices. Scope is caller-team only: this tool CANNOT see cross-team agents and MUST NOT be used to verify whether a cross-team recipient exists. DO NOT call list_agents as a pre-flight / pre-verify / pre-check step before send_message — neither for same-team nor for cross-team sends. For cross-team targets the pre-check will always falsely report "missing" because list_agents is caller-team scoped; for same-team targets the pre-check is pure waste. The canonical miss signal is the unknown_recipient error returned by send_message itself. The correct pattern is "try send, then handle unknown_recipient" — never "list_agents first, then send".

Inputs: no named parameters.

pre_register_codex_panePre-register codex tmux paneA

Pre-register a pending tmux-pane claim so the launcher can claim a tmux pane before starting codex. The launcher should call this with $TMUX_PANE and a freshly generated UUID, then exec codex --remote ... -c xats.agent_id="\"<uuid>\"". When the codex agent later calls register_agent({agent_type:"codex"}) without ui_pid, the daemon uses the pending row to resolve the correct UI pid and auto-bind the pane. Callable without a prior register_agent — launchers have no agent identity yet. TTL defaults to 120 seconds and is capped at 600; pending rows are garbage-collected opportunistically.

Inputs: pane_id (required), xats_agent_id (required), ttl_seconds.

reconnectReconnect to xats by ui_pidA

Recover this session's prior xats identity when you no longer remember your own (team, name) — for example after a context clear, where the Claude UI process ($PPID) is unchanged but the MCP/channel session is fresh and bind_channel returns unknown_agent. Prefer this over the bind_channel→register_agent fallback for re-establishing on a fresh session: it re-establishes the identity AND rebinds the channel in one call. Route by whether you still remember your (team, name): if you DO remember it after a restart + resume (you closed Claude Code and resumed the conversation, so $PPID has CHANGED but the context survived), call register_agent with that remembered (team, name) and the current $PPID instead of reconnect — reconnect would reverse-look-up the changed $PPID, find no match, and return need_register. Use reconnect only when you do NOT remember your (team, name). Invoke this when the user asks to "reconnect xats", "re-register xats", "重连 xats", or "重新注册 xats". ui_pid is the Claude UI process id — pass $PPID from a Bash tool call inside Claude Code (the same value register_agent takes as ui_pid). The daemon reverse-looks-up the most recent local claude-code agent row whose runtime_ui_pid matches ui_pid, then re-establishes that identity (cross-session takeover + channel/pane auto-bind) reusing the existing agent_id. On a single match: returns { ok, agent_id, name, team, channel_session_id, last_seen_at }. On zero matches: returns { need_register, reason } — reconnect does NOT auto-register; call register_agent to create a new identity. On multiple matches (e.g. the same UI process previously registered under two names): returns { ambiguous, candidates } ordered by last_seen_at descending — surface them so the user can pick, then register_agent with the chosen name. Each candidate/match carries last_seen_at; if it looks stale the matched ui_pid may have been reused by an unrelated process — surface it to the user before trusting the recovered identity. Scope is the daemon's configured local device label for claude-code only; codex (thread_id-based) reconnect is out of scope.

Inputs: ui_pid (required).

register_agentRegister agentA

Register this session as an agent in a team. This is the unified registration entry point. DETECTION (run these probes BEFORE choosing agent_type=, in order; first match wins): 1. printenv OPENCODE_XATS_BASE_URL non-empty → agent_type="opencode"; pass that value as base_url. Do NOT pass session_id — the daemon auto-resolves it as the most recently updated session on that base_url. The env var is set ONLY by the free-xats-opencode launcher, so its presence is itself the runtime assertion that the caller is opencode. 2. printenv CODEX_THREAD_ID non-empty → agent_type="codex"; pass that value as thread_id (REQUIRED for codex per the schema). Do NOT pass ui_pid (the launcher's pre_register_codex_pane flow handles tmux pane binding; supplying ui_pid from codex disables that auto-bind path). 3. printenv CLAUDECODE non-empty OR printenv CLAUDE_CODE_ENTRYPOINT non-empty → agent_type="claude-code"; pass $PPID as ui_pid to enable channel auto-bind. 4. None of the above → agent_type="custom" with agent_type_name="<the harness you are running under, e.g. cursor, opencode, ...>" (agent_type_name is required when agent_type="custom"). Detect the harness name from your runtime environment if you can — e.g. printenv CURSOR_TRACE_ID non-empty means cursor — but do NOT guess from system-wide signals like "binary X exists on PATH": such probes detect what the user has installed, not what runtime you are inside, and pick the wrong agent type. When unsure, prefer agent_type_name="unknown" over a wrong guess. Calling this tool again with the same (device, team, name) identity reuses the existing agent_id and refreshes tmux_pane_id and model; no duplicate row is created. Use agent_type="custom" for unsupported agent harnesses; provide agent_type_name for observability. opencode sessions: pass agent_type="opencode" and base_url (from $OPENCODE_XATS_BASE_URL, set by the free-xats-opencode launcher). Omit session_id — the daemon auto-resolves it via <base_url>/session (most recently updated). auth_token_ref is optional; set only when OPENCODE_SERVER_PASSWORD is configured on the opencode server. The schema REQUIRES base_url (parseable http:// or https:// URL) when agent_type="opencode"; missing/malformed base_url is rejected before any HTTP probe runs. Claude Code sessions: pass agent_type="claude-code" and PREFERRED: pass only ui_pid (from $PPID) so the daemon auto-binds channel delivery — do not pass channel_session_id explicitly. When BOTH ui_pid AND channel_session_id are supplied, the daemon runs a consistency check against the caller ui_pid's live channel proxy; if the proxy's csid does not match the supplied channel_session_id, the call is rejected with channel_session_id_ui_pid_mismatch before any agent row is written. To re-establish a prior identity on a fresh/resumed session where you no longer remember your (team, name) (changed csid, unchanged $PPID), prefer reconnect({ ui_pid }) over the bind_channel→register fallback; bind_channel only rebinds a session already bound to your agent. If instead you still remember your (team, name) after a restart + resume (changed $PPID), call register_agent directly with that remembered (team, name) and the current $PPID rather than reconnect. Codex sessions: pass agent_type="codex" and thread_id (from $CODEX_THREAD_ID) to register Codex app-server delivery. The schema REQUIRES thread_id when agent_type="codex"; missing or empty thread_id is rejected before any handshake runs. Launcher pre-reg callers without thread_id should use pre_register_codex_pane instead. ws_url defaults to ws://127.0.0.1:8799 (env override CROSS_AGENT_TEAMS_CODEX_WS_URL); model defaults to gpt when omitted. For agent_type="claude-code" callers, model defaults to a Claude-specific value derived from MCP session client info when omitted. model is OPTIONAL for any agent_type: omit it when you do not have an authoritative model identifier; the daemon stores NULL in that case. Pass an explicit model only when you have a stable identifier you would like surfaced via list_agents. Requests such as "register to xats" or "register to cross-agent-teams" refer to this MCP service, not to the team field; do not set team to xats or cross-agent-teams from those phrases. Do not treat the bare word "register" as a request for this tool unless the current conversation is already about cross-agent-teams registration. If the user writes an identity in the shorthand name(team) (e.g. skills-creator(default) means name=skills-creator, team=default), split it into the separate name and team arguments. The daemon does NOT parse name(team); passing the literal string as name registers a malformed identity (the parentheses are not rejected). When the end user has not explicitly specified team, callers should pass project_dir as the current working directory so the daemon derives a project-scoped default team from its basename; if omitted, it falls back to default. REPORTING RULE: on success the response carries the actual team the daemon assigned. When summarizing the registration to the user, surface that returned team value verbatim; NEVER derive or paraphrase the team from project_dir, cwd, or your own pre-call assumption. Failing to read the response masks the daemon's default fallback (e.g. when project_dir was forgotten) and produces misleading "team: X (from cwd basename)" reports that break later cross-team send_message diagnostics. agent_type must describe the runtime behind ui_pid, not merely the current MCP caller. For example, if ui_pid points at an external editor process, pass agent_type="custom" with agent_type_name=<editor> even when the registration request is issued from a different harness. STRONGLY RECOMMENDED: pass ui_pid unless it is truly unobtainable (codex and opencode callers excepted). Without it, automatic runtime binding usually fails to converge and tmux-based cross-agent poke delivery stays off until a separate bind_runtime_identity(...) call. From Claude Code, $PPID inside a Bash tool call is the claude CLI pid. With ui_pid the daemon binds via verified pid → tty → pane evidence in one shot. After registration, the daemon best-effort attempts runtime binding for recognized local clients so tmux-based poke delivery can come up without a second tool call. If automatic runtime binding does not converge, call bind_runtime_identity(...) explicitly so the daemon can verify and persist your pane binding. detect_tmux_pane(...) remains available as a debugging aid for ambiguous or missing matches, but it does not write registry state by itself. When registration still has no usable tmux_pane_id, tmux-based poke delivery stays unavailable until automatic or explicit runtime binding succeeds.

Inputs: name (required), agent_type (required), role, team, +13 more.

send_messageSend messageA

Private 1→1 message to another agent by name. By default auto-poke=true with quiet-guard (auto_poke:false opts out), and need_reply=true. Set need_reply:false for FYI/no-response-needed messages; recipients see need_reply in get_inbox. to_agent_name is the target's name within its team; bare names resolve on the caller's device, and name:device targets a specific device. For UUID-based sends use send_message_by_id. If the user refers to a recipient in the shorthand name(team) (e.g. skills-creator(default)), split it into to_agent_name=skills-creator and to_team=default. The daemon does NOT parse name(team), so the literal string fails to resolve (unknown_recipient). This is distinct from the name:device suffix, which the daemon DOES parse. REPLY RULE: when replying to a message returned by get_inbox, treat its from_device as authoritative — if it differs from your own device, you MUST send to from_name + ":" + from_device (bare from_name would resolve on YOUR device and miss the actual sender). Same-device replies can use the bare name. The safe fallback for unknown device is send_message_by_id({to_agent_id: from_agent_id, ...}). For multi-recipient use broadcast (same-team) or broadcast_to_role (same-team, by role). 除非用户明确指定 to_team, 不要跨 team 沟通 (explicitly set to_team only when user asks). Reports poked, poke_skip_reasons (no_pane, guard_failed, tmux_unavailable, self); on guard_failed daemon retries at 30s/180s/600s (retry_scheduled, retry_delays_s); stops early on poked. Auto-poke injects only a SHORT wake-up hint (新邮件 from , 请调 get_inbox 查看), NOT the body — read bodies via get_inbox. Delivery is NOT filtered by online/idle; direct and fan-out deliveries write mailbox rows for offline targets. The list_agents online flag reflects process liveness. DO NOT pre-verify the recipient via list_agents before calling send_message — this rule applies to BOTH same-team and cross-team sends (list_agents is caller-team scoped and CANNOT see cross-team agents, so a cross-team pre-check always falsely reports "missing"; for same-team sends the pre-check is pure waste). On miss send_message returns unknown_recipient cleanly with no side effects, so the correct pattern is "try send, then handle unknown_recipient" — never "list_agents first, then send".

Inputs: body (required), to_agent_name (required), subject, to_team, +2 more.

send_message_by_idSend message by idA

Private 1→1 message to another agent by agent_id (UUID). Use this when you already hold the target's agent_id; prefer send_message (by name) otherwise. Same-team only: the recipient must belong to the caller's team. For cross-team sends use send_message with to_team. By default auto-poke=true with quiet-guard (auto_poke:false opts out), and need_reply=true. Set need_reply:false for FYI/no-response-needed messages. Reports poked, poke_skip_reasons (no_pane, guard_failed, tmux_unavailable, self); on guard_failed daemon retries at 30s/180s/600s (retry_scheduled, retry_delays_s); stops early on poked. Auto-poke injects only a SHORT wake-up hint (新邮件 from , 请调 get_inbox 查看), NOT the body — read bodies via get_inbox. Delivery is NOT filtered by online/idle — offline targets still receive the mailbox row.

Inputs: body (required), to_agent_id (required), subject, auto_poke, +1 more.

subscribe_channel_wakeSubscribe channel wakeA

Internal tool reserved for the cross-agent-teams-mcp channel proxy. Attaches the caller's MCP session notification sink to a channel_session_id so the daemon can emit notifications/channel_wake to it. Requires role=channel_proxy.

Inputs: channel_session_id (required).

unregister_selfUnregister current agentA

Remove the caller session's current agent registration. This tool only unregisters the currently bound agent identity; it does not delete other agents. On success it deletes the agent row and immediately releases the current MCP session back to an unregistered state.

Inputs: no named parameters.

xats_bindBind this session to an xats identityA

Bind this MCP session to the Claude Code identity that the xats SessionStart hook already registered for you. Call it once per session, before or after other xats tools, when they report unknown_agent. Pass the bind code from the xats context block (a value like "K7QM-2XPD"). Codes are single use and expire after 15 minutes. Never ask the user for the code and never invent one: it is provided in the injected context, and registration on the daemon already happened. If no code is available, use register_agent instead, which binds the session the same way.

Inputs: code (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 17 tools

    Disambiguation3/5

    Messaging tools (send_message, send_message_by_id, broadcast, broadcast_to_role, get_inbox, get_delivery_status) are clearly differentiated by target and fan-out semantics. However, the identity layer is crowded: xats_bind, register_agent, reconnect, bind_channel, bind_runtime_identity, pre_register_codex_pane, and detect_tmux_pane all orbit the same 'who am I / which pane' problem, and only the very long descriptions keep them apart. Two tools (subscribe_channel_wake, pre_register_codex_pane) are reserved for internal proxies/launchers, adding further noise for a normal agent.

    Naming Consistency4/5

    Consistent snake_case verb_noun pattern throughout (send_message, get_inbox, list_agents, register_agent, unregister_self, bind_channel, detect_tmux_pane), with suffixes like _by_id and _to_role used predictably. Minor deviations: the xats_ prefix on a single tool (xats_bind), a bare noun-verb verb (reconnect, echo) that break the pattern.

    Tool Count3/5

    17 tools is at the heavy end for a messaging/identity server, and the count is inflated by arguably non-core entries: echo is a trivial filler and subscribe_channel_wake plus pre_register_codex_pane are internal-only paths. The remaining surface is roughly commensurate with the domain, so it's borderline rather than wildly oversized.

    Completeness4/5

    Strong lifecycle coverage: registration, reconnect, unregister, channel/pane binding, private and broadcast messaging, inbox read with cursor semantics, and delivery status. Gaps are minor-to-moderate: no cross-team agent discovery, no agent-detail lookup, no message deletion or acknowledgement, and no team management operations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that connects AI coding agents (Claude Code, Codex, Cursor, etc.) on the same machine via a shared message bus, enabling them to chat, delegate tasks, and collaborate privately without cloud or internet.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP central server that lets multiple AI agents (e.g., Claude Code, kimi-code) exchange private messages, shared channel broadcasts, and unified message streams via MCP tools, with SQLite persistence and per-connection identity binding.
      97 npm
      MIT