How Claude Code Agents Communicate: Protocols, Ports and App Integration

For learning and information only. This document describes how Claude Code agents and sessions talk to each other, as observed and documented on 13 October 2026. Several of the mechanisms below are internal to Claude Code and are not published by Anthropic as an interface for users or developers to build on. The local socket protocol in particular is undocumented. Features marked research preview or experimental can change or disappear in any release. For anything you build, use the supported interfaces in "How your own apps can talk to Claude agents" and check the current documentation first.

Key takeaways

• Claude Code opens no inbound network ports. In a test, running sessions held no listening TCP port, only outbound HTTPS connections on port 443 to Anthropic's published address range. Anthropic says Remote Control "makes outbound HTTPS requests only and never opens inbound ports".
• Scope decides the transport. Subagents run inside their parent session. Agent-team teammates exchange JSON mailbox files. Separate sessions on one machine message each other over a per-session Unix socket (a named pipe on Windows) that "never" goes through Anthropic's servers. Sessions on different machines, or in the cloud, are relayed through Anthropic over Remote Control.
• Every agent still needs the internet to think. The model runs on Anthropic's servers, so a session that receives a local message cannot act on it without its API connection.
• Session-to-session messaging is not an app interface. Websites, Node.js and Python apps should use the Agent SDK, headless mode, MCP, HTTP hooks, Channels or routines. A browser connects to your own server over WebSocket, and your server runs the agent.
• Messages between agents carry no user authority. A message from another session cannot approve a permission prompt or change settings, and inbound messages can be accepted, held or refused.

How to read this document

All facts are stated as of 13 October 2026. Vendor marks facts from Anthropic's documentation and changelog. Observed marks what a read-only test found on one Linux server running Claude Code 2.1.296 with two interactive sessions on 13 October 2026. Unverified marks items that could not be confirmed. Agent frameworks and MCP in general are covered in Agent frameworks and protocols, security in Regulation and security, and model and agent costs in Claude orchestration and cost and Connector token cost.

Three scopes of communication

Subagents

A subagent works in its own context window. When it finishes, its result returns to the main conversation as a summary. Each call starts a new instance, which can be resumed by ID with its full history. Subagents can run in the background, and their results then arrive as a notification in a later turn (Vendor; Claude Code subagents). Background agents were added in version 2.0.60 (Vendor; Claude Code changelog).

Agent teams

Agent teams are experimental and need CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Teammates are separate Claude Code instances in interactive sessions only, not in headless -p runs. Messages go to a JSON mailbox at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json, and the shared task list lives in ~/.claude/tasks/{team-name}/ with file locking for task claims. Teammates inherit the lead's permission mode, there is one team per session, and teams cannot be nested (Vendor; Claude Code agent teams). Teams were added as a research preview in 2.1.32 (Vendor; Claude Code changelog).

Separate sessions on the same machine

Cross-session messaging arrived in 2.1.224 on macOS, Linux and WSL2, and in 2.1.234 on native Windows. Sessions find peers with the ListAgents tool (or /list-agents, alias /peers) and send plain text with SendMessage. On one machine, delivery uses a per-session Unix domain socket or named pipe restricted to the operating-system user, and "never" passes through Anthropic's servers. Messages arrive between tool calls, and an idle session starts a new turn. A same-machine message can be about one million characters (Vendor; Claude Code cross-session messaging; Claude Code changelog).

What a test showed on Linux (Observed):

• Each running session registers a small JSON file in ~/.claude/sessions/<pid>.json with its name, status, socket path and a peer protocol version (peerProtocol: 1).
• Each interactive session listens on a Unix socket at /run/user/<uid>/cc-socks/<pid>.sock with owner-only permissions (srw-------). The documentation names /tmp/cc-socks-<uid> as a fallback location (Vendor; Claude Code cross-session messaging).
• Neither session had a listening TCP port.

The wire format on that socket is not documented (Unverified). Do not build tools on it: it is an internal channel and can change in any release.

Sessions on different machines: Remote Control

Remote Control lets claude.ai or the Claude app drive a session that runs on your own machine. The local process "makes outbound HTTPS requests only and never opens inbound ports". It registers with the Anthropic API, and the server routes messages from the web or app to it over a streaming connection. Execution and files stay on your machine; the traffic is TLS-encrypted with short-lived, purpose-scoped credentials, and transcripts are stored on Anthropic's servers while connected (Vendor; Claude Code Remote Control). The documentation does not claim end-to-end encryption.

Cross-machine SendMessage uses the same route: messages to a session on another machine, or to a cloud session, go through Anthropic's servers over the target's Remote Control connection. No LAN or peer-to-peer mode is documented. The receiver cannot reply when the sender has no Remote Control connection to reply to (Vendor; Claude Code cross-session messaging).

Requirements and limits (Vendor; Claude Code Remote Control):

• A claude.ai sign-in on a Pro, Max, Team or Enterprise plan. API keys, Amazon Bedrock, Google Vertex AI, Microsoft Foundry and a custom ANTHROPIC_BASE_URL are not supported. Team and Enterprise owners must enable it; zero-data-retention and HIPAA organisations cannot.
• The local process must keep running (for example in tmux or screen over SSH). A session that cannot reach the API for about 30 minutes disconnects.
• One remote session per interactive process; server mode serves up to 32 by default.
• DISABLE_NONESSENTIAL_TRAFFIC turns Remote Control off.

Remote Control was added as the claude remote-control subcommand in 2.1.51 (Vendor; Claude Code changelog).

Protocols, ports and firewalls

• Inbound: none. No firewall port needs opening for any of the features above (Vendor; Claude Code Remote Control; Observed).
• Outbound: HTTPS on port 443. The documented allowlist includes api.anthropic.com, claude.ai, claude.com, platform.claude.com and mcp-proxy.anthropic.com (Vendor; Claude Code network configuration).
• Address range: in the test, every connection held by Claude Code went to one address in 160.79.104.0/23 on port 443 (Observed). Anthropic publishes that range for firewall allowlisting (Vendor; Anthropic IP addresses).
• Proxies: HTTPS_PROXY, HTTP_PROXY and NO_PROXY are honoured; SOCKS proxies are not supported (Vendor; Claude Code network configuration).

How your own apps can talk to Claude agents

Details (Vendor unless marked):

• Agent SDK. The SDK spawns the bundled CLI and talks to it with JSON lines; a custom transport is possible in Python. It supports streaming input, interrupts, session resume and forks, custom tools as in-process MCP servers, hooks and a permission callback (Agent SDK, Python). Products built on the SDK must use API keys; offering claude.ai sign-in or subscription limits to third parties needs Anthropic's approval (Agent SDK overview).
• Headless mode. JSON output includes result, session_id and total_cost_usd; --resume, --session-id and --fork-session continue conversations; --allowedTools, --permission-mode and --max-turns keep unattended runs bounded (Claude Code headless mode; Claude Code CLI reference). The input schema of --input-format stream-json was not found (Unverified).
• MCP. Streamable HTTP is the recommended remote transport; Claude Code falls back to SSE when needed, and claude mcp serve exposes Claude Code itself as a stdio MCP server (Claude Code MCP).
• HTTP hooks. A hook of type http posts the event JSON to a URL. A 2xx JSON reply is the decision; a failed connection does not block unless onFailure: "block" is set. The default timeout is 600 seconds (Claude Code hooks).
• Channels. A channel is a local MCP server that Claude Code starts over stdio. It pushes events with notifications/claude/channel and can relay permission prompts. Telegram, Discord and iMessage channels are built in; custom channels need a development flag and work in interactive sessions only (Claude Code channels; Channels reference). Channels were added in 2.1.80 (Claude Code changelog).
• Routines. A POST to https://api.anthropic.com/v1/claude_code/routines/<routine_id>/fire with the routine's bearer token starts a cloud session and returns its ID and URL. The token is created on the web and shown once (Claude Code routines).
• Managed Agents. Agents, environments and sessions are created over REST, and results stream back by server-sent events (Managed Agents overview).
• GitHub Actions. Mention-driven and prompt-driven modes, with an API key or OAuth token as a repository secret (Claude Code GitHub Actions).

A browser, a WebSocket and an agent

There is no official browser protocol for Claude agents. The hosting guide places the agent behind your own server: the container exposes an HTTP or WebSocket port for your application, and the SDK's subprocess does not listen on the network (Agent SDK hosting). Anthropic's demo chat app follows the same shape, with a WebSocket between the browser and an Express server that runs the SDK; the demos are marked for local development only (Vendor; Agent SDK demos).

Browser --WebSocket--> your server --JSON over stdin/stdout--> agent process --HTTPS 443--> Anthropic API
          (your auth, rate limits, logging)                     (never exposed to the internet)

Security controls for agent messages

• Messages from other agents or sessions are shown as coming from that session, not from the user. They cannot approve prompts or change configuration, and slash commands in them arrive as plain text (Vendor; Claude Code cross-session messaging; Claude Code agent teams). Version 2.1.166 stopped relayed messages from carrying user authority (Vendor; Claude Code changelog).
• The crossSessionInbound setting accepts, holds or refuses incoming messages; held messages expire after five minutes by default. isolatePeerMachines keeps messages to the local machine, and deny rules on SendMessage or ListAgents switch messaging off (Vendor; Claude Code cross-session messaging).
• Same-machine sockets are limited to the same operating-system user, so sessions running as different users cannot message each other (Vendor; Observed).

What this means for your business

These points are inferences from the evidence above, not sourced forecasts.

1. No ports to open, but plan for outbound HTTPS. Agents need port 443 to Anthropic's domains. Allowlist those, and route through an HTTPS proxy if your network requires one.
2. Build on supported interfaces only. For websites and apps, use the Agent SDK or headless mode behind your own server, MCP for your data, and HTTP hooks for audit. Treat session-to-session messaging and the local socket as internal features that may change.
3. Never put an agent straight on the internet. Let browsers talk to your server, and run the agent as a low-privilege user or in a container with a short tool allowlist, especially when it handles input from the public.
4. Separate personal and product accounts. Remote Control and cross-machine messaging need a claude.ai sign-in; products for customers need API keys.
5. Re-check after updates. These features change between releases. Read the changelog before relying on any behaviour described here.

Open questions and unverified items

• The message format on the local session socket is not documented (Unverified).
• The schema of --input-format stream-json and the SDK's control messages were not found in the documentation (Unverified).
• Whether Remote Control reuses the same outbound connections seen in the test was not checked (Unverified).
• How agent-team mailbox messages are picked up (polling or file watching) is not documented (Unverified).
• The changelog was read in sections, so some version entries may be missing (Unverified).

Sources

1. Claude Code cross-session messaging
2. Claude Code Remote Control
3. Claude Code network configuration
4. Anthropic IP addresses
5. Claude Code subagents
6. Claude Code agent teams
7. Claude Code changelog
8. Agent SDK overview
9. Agent SDK, Python
10. Agent SDK hosting
11. Agent SDK demos
12. Claude Code headless mode
13. Claude Code CLI reference
14. Claude Code MCP
15. Claude Code hooks
16. Claude Code channels
17. Channels reference
18. Claude Code routines
19. Managed Agents overview
20. Claude Code GitHub Actions