Register agent
register_agentRegisters an agent session with the local Cross-Agent Teams daemon, enabling team identity, discovery, and cross-agent messaging; detects Codex, Claude Code, OpenCode, and custom runtimes.
Instructions
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>",
"agent_type": "<agent_type>"
},
"name": "register_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| role | No | ||
| team | No | ||
| model | No | ||
| device | No | ||
| ui_pid | No | STRONGLY RECOMMENDED. Visible agent UI process pid (e.g. Claude Code CLI pid — `$PPID` from a Bash tool call inside Claude Code). Enables one-shot pid → tty → pane binding at registration; without it, tmux-based cross-agent poke delivery typically stays off. | |
| ws_url | No | ||
| base_url | No | ||
| delivery | No | ||
| thread_id | No | ||
| agent_type | Yes | ||
| session_id | No | ||
| project_dir | No | ||
| claude_ui_pid | No | Internal field for the cross-agent-teams-mcp channel proxy. Stores the proxy's parent Claude Code UI pid (`process.ppid`) so that Claude Code hosts registering in the same lineage can auto-bind their claude-channel delivery. Only valid when role='__channel_proxy__'; rejected otherwise. | |
| auth_token_ref | No | ||
| agent_type_name | No | ||
| channel_session_id | No |