cc:// Protocol
- Entity ID:
ent-20260409-ad6b72350de8 - Type:
service - Scope:
shared - Status:
active - Aliases: cc:// protocol, DIRECT_CONNECT, remote session control
Description
The cc:// protocol is a deep link system that enables remote session control of Claude Code from external devices such as phones, tablets, or web browsers. It works in conjunction with the DIRECT_CONNECT subsystem to establish secure connections between a running Claude Code CLI session and remote clients. This enables use cases like monitoring a long-running agent session from a phone or issuing commands from a browser while the agent runs on a development workstation.
Architecture
The system operates through a local server architecture:
- Local server -- When
DIRECT_CONNECTis enabled, Claude Code starts a lightweight HTTP/WebSocket server on a configurable local port. - Deep link registration -- The
cc://protocol scheme is registered with the operating system, so clicking acc://link (e.g.,cc://session/abc123) opens a connection to the appropriate local session. - Authentication -- Remote clients authenticate using a session-specific token generated at server startup. The token can be shared via QR code displayed in the terminal or copied to clipboard.
- Transport -- Once authenticated, communication flows over WebSocket with the same message format used by the bridge-system, enabling full bidirectional control.
Capabilities
| Action | Description |
|---|---|
| Monitor | View the agent's streaming output in real time from a remote device |
| Send messages | Type user messages from a phone or browser to the running agent |
| Approve permissions | Respond to permission-pipeline prompts remotely |
| Cancel operations | Send interrupt signals to cancel long-running tool executions |
| Session info | View session metadata, token usage, and elapsed time |
DIRECT_CONNECT System
The DIRECT_CONNECT system is the server-side component that manages inbound connections. It is controlled by the BRIDGE_MODE flag (see bridge-system) and supports multiple simultaneous remote clients connected to the same session. Each client receives the full streaming output, but only one client can send input at a time to prevent conflicts.
Security Considerations
Remote session control introduces a significant attack surface. The system mitigates risks through:
- Session-specific tokens that expire when the session ends.
- Local-only binding by default (the server listens on
127.0.0.1), requiring explicit configuration to expose on a network interface. - Rate limiting on authentication attempts to prevent token brute-forcing.
- TLS encryption when exposed beyond localhost.
The three-layer-verification system applies to remote-originated commands with the same rigor as local commands.
Integration
The cc:// protocol reuses the bridge-system's message format and transport abstractions, so the same queryengine-ts instance serves both local and remote clients. The hooks-system fires events for remote connections, and session-persistence ensures that remote clients can reconnect after network interruptions without losing session state.
Key claims
- none yet
Relations
- none yet
Sources
src-20260409-1ef27ff0b214