claude-remote-protocol

Reverse-engineered TypeScript client for the Claude Code Remote (CCR) WebSocket protocol. Built by analyzing live claude.ai frontend traffic via Chrome DevTools Protocol.

Warning: This is an unofficial library based on reverse-engineering the undocumented Claude Code Remote protocol. The protocol may change without notice. Use at your own risk.

Features

• Full WebSocket session management with automatic reconnection
• HTTP REST API client for sessions, events, and environments
• Streaming assistant messages (thinking, text, tool_use)
• Tool permission handling (allow/deny with input modification)
• AskUserQuestion flow (single-select & multi-select)
• Plan mode support (EnterPlanMode / ExitPlanMode)
• MCP server status and message forwarding
• Keep-alive and idle timeout management
• Complete TypeScript types for the entire protocol

Install

npm install claude-remote-protocol

Requires Node.js >= 18 (uses native fetch and WebSocket).

For Node.js < 22 (no native WebSocket), you may need to polyfill globalThis.WebSocket with the ws package.

Quick Start

import { ClaudeClient } from "claude-remote-protocol";

// 1. Create client (pass credentials once)
const client = new ClaudeClient({
  organizationUuid: "your-org-uuid",
  sessionKey: "sk-ant-sid02-...",
  cfClearance: "...",
  userAgent: "Mozilla/5.0 ...",
});

// 2. Connect to an existing session
const session = await client.connect("session_01...", {
  onAssistantMessage(msg) {
    for (const block of msg.message.content) {
      if (block.type === "text") process.stdout.write(block.text ?? "");
    }
  },
  onResult(msg) {
    console.log(`Done: ${msg.num_turns} turns, $${msg.total_cost_usd}`);
  },
});

await session.sendMessage("Hello, Claude!");

// 3. Or create a new session (auto-selects active environment)
const newSession = await client.create({
  model: "claude-sonnet-4-6",
  title: "My Task",
  onAssistantMessage(msg) { /* ... */ },
});

await newSession.sendMessage("Start working on the task.");

// 4. Multiple sessions in parallel
const [s1, s2] = await Promise.all([
  client.connect("session_A", { onResult(m) { console.log("A done"); } }),
  client.connect("session_B", { onResult(m) { console.log("B done"); } }),
]);

// 5. Cleanup
client.disconnectAll();

Architecture

The protocol uses a dual-channel design:

| Channel | Direction | Purpose | |---------|-----------|---------| | WebSocket (/v1/sessions/ws/{id}/subscribe) | Server → Client | Streaming responses, control requests | | HTTP POST (/v1/sessions/{id}/events) | Client → Server | User messages, tool permissions, interrupts |

Messages on the WebSocket are newline-delimited JSON.

Message Flow

Client                          Server
  │                                │
  │──── HTTP POST (user msg) ─────▶│
  │                                │
  │◀──── WS: assistant (stream) ──│  (thinking → text → tool_use)
  │◀──── WS: assistant (stream) ──│  (same msg_id, incremental)
  │◀──── WS: control_request ─────│  (can_use_tool permission)
  │                                │
  │──── WS: control_response ─────▶│  (allow/deny)
  │                                │
  │◀──── WS: assistant (stream) ──│  (tool_result → more text)
  │◀──── WS: result ──────────────│  (execution summary)

API Reference

ClaudeClient

Top-level entry point. Pass credentials once, manage multiple sessions.

const client = new ClaudeClient({
  organizationUuid: string,
  sessionKey: string,          // sk-ant-sid02-...
  cfClearance: string,         // Cloudflare cf_clearance cookie
  userAgent: string,           // must match browser that generated cfClearance
  cookie?: string,             // full cookie override (sessionKey/cfClearance ignored)
  baseUrl?: string,            // default: "https://claude.ai"
});

// Connect to existing session (returns connected SessionManager)
const session = await client.connect(sessionId, {
  replay?: boolean,
  maxRetries?: number,
  idleTimeout?: number,
  onAssistantMessage?, onResult?, onToolPermission?, onError?,
});

// Create new session + connect (auto-selects environment if omitted)
const session = await client.create({
  environmentId?: string,
  model?: string,           // default: "claude-sonnet-4-6"
  title?: string,
  sessionContext?: Partial<SessionContext>,
  // ...same callbacks as connect
});

await client.listSessions();
await client.listEnvironments();
client.getConnected(sessionId);   // get a previously connected session
client.disconnect(sessionId);     // disconnect one
client.disconnectAll();           // disconnect all

ClaudeApi

HTTP REST client for session management (also accessible via client.api).

const api = new ClaudeApi({
  organizationUuid: string,
  sessionKey: string,
  cfClearance: string,
  userAgent: string,
  cookie?: string,             // full cookie override
  baseUrl?: string,
});

await api.listSessions();
await api.getSession(sessionId);
await api.createSession({ environment_id, session_context });
await api.updateSession(sessionId, { title?, session_status? });
await api.listEvents(sessionId, afterId?);
await api.sendMessage({ sessionId, uuid, message });
await api.interrupt(sessionId);
await api.respondToolPermission({ sessionId, requestId, toolName, decision });
await api.setPermissionMode(sessionId, mode);
await api.listEnvironments();

SessionManager

High-level WebSocket session manager.

const session = new SessionManager({
  // Required
  organizationUuid: string,
  sessionKey: string,
  cfClearance: string,
  userAgent: string,
  sessionId: string,

  // Optional
  replay?: boolean,           // Replay missed messages on connect
  maxRetries?: number,        // Reconnect attempts (default: 5)
  idleTimeout?: number,       // Idle disconnect in ms (default: 300000)
  baseUrl?: string,
  wsHost?: string,            // Custom WebSocket host

  // Callbacks
  onAssistantMessage?: (msg: WsAssistantMessage) => void,
  onResult?: (msg: WsResultMessage) => void,
  onToolPermission?: ToolPermissionHandler,
  onHookCallback?: HookCallbackHandler,
  onStateChange?: (state: ConnectionState) => void,
  onError?: (error: Error) => void,
});

await session.connect();
await session.sendMessage("Hello!");
await session.interrupt();
await session.setModel("claude-sonnet-4-6");
await session.setPermissionMode("acceptEdits");
await session.setMaxThinkingTokens(10000);
session.disconnect();

Streaming Pattern

Assistant messages arrive incrementally with the same msg_id. Content blocks build up over time:

1. First message: [thinking]
2. Next: [thinking, text]
3. Next: [thinking, text, tool_use]
4. Final: stop_reason changes from null to "end_turn" or "tool_use"

Tool Permission Flow

When Claude wants to use a tool, the server sends a can_use_tool control request. Your handler decides whether to allow or deny:

onToolPermission: async (toolName, input, { toolUseID, signal, suggestions }) => {
  if (toolName === "Bash") {
    return { behavior: "deny", message: "Bash not allowed" };
  }
  return { behavior: "allow", updatedInput: input };
},

Content Block Types

| Type | Fields | Description | |------|--------|-------------| | text | text | Plain text output | | thinking | thinking, signature | Extended thinking (encrypted signature) | | tool_use | id, name, input | Tool invocation | | tool_result | tool_use_id, content, is_error | Tool execution result | | tool_reference | tool_name | Reference to a tool | | image | | Image content | | resource | | Resource reference |

Protocol Documentation

See PROTOCOL.md for the complete protocol specification with all message types and flows.

Authentication

All credentials can be extracted from any claude.ai page (homepage, settings, any conversation — no need to open a specific session).

Step-by-step extraction

1. Open DevTools — Press F12 on any claude.ai page

2. Get sessionKey and cfClearance from Cookies:

• Go to Application tab → Cookies → https://claude.ai
• Find sessionKey — value starts with sk-ant-sid02-...
• Find cf_clearance — a long alphanumeric string

3. Get organizationUuid:

• Option A: In Application → Cookies, find lastActiveOrg — that's your org UUID
• Option B: In Network tab, click any request to claude.ai/v1/..., check the x-organization-uuid request header

4. Get userAgent:

• Go to Console tab, type navigator.userAgent and press Enter
• Copy the full string (e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...)
• Important: This must be the exact User-Agent of the browser that generated the cf_clearance cookie. Using a different User-Agent will result in Cloudflare 403 errors.

Notes

• cf_clearance expires periodically (typically when Cloudflare re-challenges). If you get 403 errors, re-extract it.
• sessionKey is long-lived but can be invalidated by logging out.
• All four cookies are set at the claude.ai domain level, so they are the same on every page.

Usage

import { ClaudeClient } from "claude-remote-protocol";

const client = new ClaudeClient({
  organizationUuid: "ed81b697-...",
  sessionKey: "sk-ant-sid02-...",
  cfClearance: "DrW9nrPr...",
  userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...",
});

Programmatic extraction (CDP)

If you have a Chrome instance with remote debugging enabled (--remote-debugging-port=9222), you can extract credentials programmatically:

// Get cookies via Chrome DevTools Protocol
const resp = await fetch("http://localhost:9222/json");
const [tab] = await resp.json();
// Connect to tab via WebSocket, then:
// - Network.getCookies({ urls: ["https://claude.ai"] }) → sessionKey, cf_clearance, lastActiveOrg
// - Browser.getVersion() → userAgent

License

MIT