| echoD | |
| xats_bindA | 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. |
| pre_register_codex_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. |
| detect_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. |
| register_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. |
| reconnectA | 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. |
| unregister_selfA | 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. |
| list_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". |
| send_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". |
| send_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. |
| broadcastA | 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. |
| broadcast_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. |
| get_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. |
| get_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. |
| bind_channelA | 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). |
| bind_runtime_identityA | 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. |
| subscribe_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. |