Skip to main content
Glama

Register agent

register_agent

Registers 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

NameRequiredDescriptionDefault
nameYes
roleNo
teamNo
modelNo
deviceNo
ui_pidNoSTRONGLY 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_urlNo
base_urlNo
deliveryNo
thread_idNo
agent_typeYes
session_idNo
project_dirNo
claude_ui_pidNoInternal 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_refNo
agent_type_nameNo
channel_session_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden and does: idempotency semantics (same (device, team, name) reuses agent_id and refreshes tmux_pane_id/model, no duplicate row), pre-flight rejection paths (malformed base_url, missing thread_id, channel_session_id_ui_pid_mismatch all fail before any row is written), defaults for ws_url and model plus NULL storage when omitted, and best-effort runtime binding with bind_runtime_identity as the fallback. That is unusually rich disclosure for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is front-loaded well, with detection first and per-harness detail after, but the text is heavily redundant: the opencode paragraph restates detection step 1 almost verbatim, and the codex and claude-code instructions are each given twice (detection phase, then 'opencode sessions:'/'Codex sessions:'/'Claude Code sessions:' sections). Large stretches read as caller-side prompt scaffolding rather than tool documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 17 parameters, no annotations, and no output schema, the description covers what an agent needs to call correctly: argument selection per runtime, defaults, failure modes, and the reporting rule that the assigned team comes back in the response rather than being inferred from cwd. The complexity justifies the length, even if the presentation repeats itself.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 12% across 17 parameters, so the description must compensate, and it largely does: it defines agent_type, agent_type_name, base_url, session_id, thread_id, ui_pid, ws_url, model, auth_token_ref, project_dir, and channel_session_id semantics and constraints, including the name(team) shorthand that the daemon will not parse. Minor gaps remain (role, delivery, and device are never explained beyond passing mentions), which keeps it from being flawless.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: "Register this session as an agent in a team," then adds "This is the unified registration entry point," which separates it from siblings like pre_register_codex_pane, bind_channel, and reconnect. An agent can identify the tool's role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit ordered detection procedure (printenv OPENCODE_XATS_BASE_URL → CODEX_THREAD_ID → CLAUDECODE/CLAUDE_CODE_ENTRYPOINT → custom) with 'first match wins', plus named alternatives and the conditions that select them: pre_register_codex_pane for launcher pre-reg without thread_id, reconnect({ui_pid}) for a forgotten identity, bind_channel only for already-bound sessions. It also warns against misreading phrases like 'register to xats' or the bare word 'register' as a request for this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.