Skip to main content
Glama

Reconnect to xats by ui_pid

reconnect

Recover a forgotten xats team/name identity by UI process ID and rebind the channel in one call after a context clear or fresh MCP session.

Instructions

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.

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": {
      "ui_pid": "<ui_pid>"
    },
    "name": "reconnect"
  }
}

Input Schema

NameRequiredDescriptionDefault
ui_pidYesThe Claude UI process id (`$PPID` from a Bash tool call inside Claude Code). The daemon reverse-looks-up the prior local claude-code identity registered under this runtime_ui_pid.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses cross-session takeover, channel/pane auto-binding, agent_id reuse, and all three response shapes (ok / need_register / ambiguous with candidates ordered by last_seen_at). It also warns that a stale last_seen_at may indicate ui_pid reuse by an unrelated process and that reconnect never auto-registers.

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

Conciseness4/5

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

Every sentence carries operational information and the primary rule is front-loaded in the first clause. It is a dense, unstructured block with mild redundancy (the no-auto-register/use-register_agent point is made twice, and $PPID is explained in both description and schema), but little is genuinely disposable.

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?

For a single-parameter recovery tool with no output schema, the description supplies everything an agent needs: trigger conditions, the competing alternative, all return variants including failure and ambiguity, staleness caveats, and the device/agent-type scope boundary.

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

Parameters4/5

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

Schema coverage is 100% and the schema already defines ui_pid as $PPID with the reverse-lookup behavior, so the baseline is 3. The description adds genuine cross-tool meaning by equating it with 'the same value register_agent takes as ui_pid' and restating the pass-$PPID-from-Bash mechanics, which the schema alone does not connect.

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?

States a specific verb and resource ('Recover this session's prior xats identity') and immediately scopes it to the case where the caller no longer remembers its (team, name). It explicitly distinguishes itself from both bind_channel (which returns unknown_agent) and register_agent, so an agent can route without opening another 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 explicit when-to-use conditions (fresh MCP/channel session after a context clear, $PPID unchanged, bind_channel returns unknown_agent) and an explicit when-NOT-to-use rule with the reason (if you remember (team, name) after restart+resume, $PPID has changed and this tool returns need_register, so call register_agent instead). It also names trigger phrasings and states the codex scope exclusion.

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