claude-ws-app

name	claude-ws-app
description	Build applications using Claude Code CLI over WebSocket (--sdk-url). Covers NDJSON protocol, message formats, process lifecycle, permissions, streaming, and known pitfalls. Use when spawning Claude CLI instances, implementing WebSocket bridges, building multi-agent orchestrators, or working with headless Claude, sdk-url, or NDJSON protocol.

Building Apps with Claude Code CLI + WebSocket

Overview

This skill covers building applications that spawn Claude Code CLI instances in headless WebSocket mode using claude --sdk-url ws://host:port/path. The CLI connects to your server as a WebSocket client, exchanging NDJSON (newline-delimited JSON) messages for full programmatic control — sending prompts, handling tool permissions, streaming responses, and managing the process lifecycle.

The typical architecture is: one or more Claude CLI instances connected via WebSocket to a server (Hono/Bun or similar), which also serves a browser UI over a separate WebSocket channel. The server acts as orchestrator — routing messages between CLI agents, managing turns, and forwarding state to the browser for human oversight.

This protocol is undocumented. Everything here was reverse-engineered from working implementations and validated through 13 bug discoveries. Follow this skill to avoid the same pitfalls.

Quick Start Checklist

Before writing any code, verify your implementation covers these 8 items. Each corresponds to a real bug that caused silent failures, crashes, or multi-hour debugging sessions.

• Message format: User messages use nested structure {type:"user", message:{role:"user", content:"..."}, parent_tool_use_id:null, session_id:""} — NOT flat {type:"user", content:"..."}
• control_request parsing: Read tool info from msg.request.subtype and msg.request.tool_name — NOT msg.request_type or msg.tool_name
• Stream deduplication: Render EITHER stream_event deltas (real-time) OR assistant messages (complete text) to UI — NEVER both (causes doubled output)
• Connection gating: Mark agent as "connected" on WebSocket open — NOT on system/init message (hooks delay init by 5-15s)
• Environment isolation: Strip CLAUDECODE from child process env before spawning (prevents "cannot be launched inside another Claude Code session" crash)
• Timer reset: Reset turn/inactivity timers on ANY CLI message — not just streaming text (tools like Read, Grep produce no streaming output)
• Tool activity detection: Don't rely on control_request for tracking auto-approved tools — parse assistant message tool_use blocks or stream_event content_block_start
• File watcher exclusion: Exclude agent working directories from dev server watch (Vite: server.watch.ignored, webpack: watchOptions.ignored)

NDJSON Message Formats

This is the #1 source of bugs. The CLI expects exact nested structures. Getting these wrong causes TypeError crashes or silent timeouts with no error messages.

Sending a user message (Server -> CLI)

// CORRECT - nested message object with required null fields
const userMessage = {
  type: "user",
  message: {
    role: "user",
    content: "Your prompt text here",
  },
  parent_tool_use_id: null,  // Required. null for top-level messages
  session_id: "",            // Required. "" works, or use session_id from init
};

// WRONG - flat structure causes TypeError: undefined is not an object
// { type: "user", content: "..." }

Sending a control_response (Server -> CLI)

// CORRECT - triple-nested response structure
const controlResponse = {
  type: "control_response",
  response: {
    subtype: "success",
    request_id: originalRequest.request_id,  // Must match the request
    response: {
      behavior: "allow",   // or "deny"
      // updatedInput: {}   // Optional: modify tool arguments
    },
  },
};

// WRONG - flat response causes silent drop, CLI waits forever
// { type: "control_response", request_id: "...", allow: true }

TypeScript types (copy-pasteable)

// Messages TO the CLI (Server -> CLI)
interface CLIUserMessage {
  type: "user";
  message: { role: "user"; content: string };
  parent_tool_use_id: string | null;
  session_id: string;
}

interface CLIControlResponse {
  type: "control_response";
  response: {
    subtype: "success";
    request_id: string;
    response: {
      behavior: "allow" | "deny";
      updatedInput?: unknown;
    };
  };
}

// Messages FROM the CLI (CLI -> Server)
interface CLIControlRequest {
  type: "control_request";
  request_id: string;
  request: {
    subtype: "can_use_tool" | "interrupt" | string;
    tool_name?: string;
    input?: unknown;
    tool_use_id?: string;
  };
  session_id?: string;
}

interface CLIAssistantMessage {
  : ;
  : {
    : ;
    : ;
    : <{
      :  |  | ;
      ?: ;
      ?: ;
      ?: ;
      ?: ;
    }>;
    ?: ;
    ?: ;
  };
  : ;
}

  {
  : ;
  : ;
  : ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
}

  {
  : ;
  : ;   
  ?: ;
}

  {
  : ;
  : ;
  : ;
  ?: [];
  ?: ;
}

  {
  : ;
}

For the full protocol specification with all message types, see protocol-reference.md.

CLI Process Spawning

Correct Bun.spawn configuration

const args = [
  "--sdk-url", `ws://localhost:${port}/ws/cli/${sessionId}/${role}`,
  "--print",
  "--output-format", "stream-json",
  "--input-format", "stream-json",
  "--verbose",          // Required for stream_event messages
];

// Add allowed tools
for (const tool of allowedTools) {
  args.push("--allowedTools", tool);
}

// Empty prompt — CLI waits for first user message over WS
args.push("-p", "");

// CRITICAL: Strip CLAUDECODE from child env
const childEnv = { ...process.env };
delete childEnv.CLAUDECODE;

const proc = Bun.spawn(["claude", ...args], {
  cwd: process.cwd(),
  env: childEnv,
  stdout: "pipe",
  stderr: "pipe",
});

Connection gating

// CORRECT: Mark connected on WebSocket open event
wss.on("connection", (ws) => {
  agent.connected = true;  // Ready to receive messages
});

// WRONG: Waiting for system/init before marking connected
// Hooks (superpowers, etc.) run first and delay init by 5-15+ seconds

Timeout

Use 30s+ for connection timeout. The CLI needs time for hooks to execute before sending system/init.

Handling control_request

When the CLI needs tool permission, it sends a control_request. The critical gotcha is the nested field path.

function handleControlRequest(role: string, msg: CLIControlRequest) {
  const req = msg.request;  // Fields are NESTED under .request

  if (req.subtype === "can_use_tool" && req.tool_name) {
    // Auto-approve safe tools
    if (SAFE_TOOLS.has(req.tool_name)) {
      sendToCLI(role, makeControlResponse(msg.request_id, true));
      return;
    }
    // Escalate risky tools to human UI
    forwardToUI(role, req.tool_name, req.input, msg.request_id);
  }
}

// WRONG field paths (silent drop, CLI waits forever):
// msg.request_type    -> undefined (field doesn't exist at top level)
// msg.tool_name       -> undefined (field doesn't exist at top level)

Streaming vs Assistant Messages

The CLI sends the same text content through TWO paths:

1. stream_event (content_block_delta): Incremental text chunks, real-time
2. assistant: Complete accumulated text after LLM finishes

Rule: Pick one for UI display. Never render both.

• Use stream_event deltas for real-time streaming UI (append each delta)
• Use assistant messages for server-side text extraction (final complete text)
• The assistant handler should update internal state only — NOT broadcast to browser

// stream_event handler: send to browser for real-time display
if (msg.event_type === "content_block_delta") {
  const text = msg.data?.delta?.text;
  if (text) broadcastToBrowsers({ type: "stream_delta", role, text });
}

// assistant handler: update server state only, DON'T broadcast
function handleAssistantMessage(role, msg) {
  const text = msg.message.content
    .filter(b => b.type === "text" && b.text)
    .map(b => b.text)
    .join("\n");
  agent.streamingText = text;  // Server-side only
  // Do NOT call broadcastToBrowsers here
}

Tool Activity Detection

Tools passed via --allowedTools are auto-approved internally by the CLI. No control_request is sent over WebSocket for these tools.

Three-layer detection approach:

// Layer 1: Parse assistant message tool_use blocks (most reliable)
for (const block of msg.message.content) {
  if (block.type === "tool_use" && block.name) {
    broadcastToolActivity(role, block.name, block.input);
  }
}

// Layer 2: Watch stream_event content_block_start (best-effort, early signal)
if (msg.event_type === "content_block_start" &&
    msg.data?.content_block?.type === "tool_use") {
  broadcastToolActivity(role, msg.data.content_block.name);
}

// Layer 3: Elapsed time ticker as guaranteed fallback
setInterval(() => {
  broadcastActivity(role, agent.currentActivity || "Working", elapsed);
}, 3000);

Activity detail persistence

When broadcasting tool activity, store the extracted detail on the agent state. The periodic ticker should read the stored detail, not overwrite it with empty string.

function broadcastToolActivity(role, toolName, input?) {
  agent.currentActivity = TOOL_LABELS[toolName] ?? `Using ${toolName}`;
  const detail = extractToolDetail(toolName, input);
  if (detail) agent.currentDetail = detail;  // Only update if non-empty
  broadcast({ activity: agent.currentActivity, detail: agent.currentDetail });
}

// Ticker reads stored detail instead of hardcoding ""
setInterval(() => {
  broadcast({ activity: agent.currentActivity, detail: agent.currentDetail });
}, 3000);

Turn Timer Best Practices

• Default timeout: 300s (5 minutes). Many tool operations (deep code search, file analysis) take 30-60s each, and agents may chain 5-10 tool calls per turn.
• Reset on ANY CLI message: Not just streaming text. Tools like Read, Grep, Glob produce no streaming output. Reset the timer on assistant, control_request, stream_event, and result messages. Only skip keep_alive and system.
• Pause during permission requests: When waiting for human to approve/deny a tool, pause the timer. Resume after response.

function handleCLIMessage(role, msg) {
  // Reset timer on any substantive message
  if (msg.type !== "keep_alive" && msg.type !== "system") {
    resetTurnTimer(role);
  }
  // ... handle message
}

Dev Server Configuration

When agents write files inside the project directory, dev servers detect changes and trigger hot/full reloads. This causes the browser UI to flash back to its initial state.

Vite

// vite.config.ts
export default defineConfig({
  server: {
    watch: {
      ignored: [
        "**/sessions/**",    // Agent session output
        "**/server/**",      // Server code (separate process)
        "**/dist/**",        // Build output
        "**/.ignore/**",     // Agent scratch space
      ],
    },
  },
});

Webpack / Next.js

// webpack.config.js or next.config.js
watchOptions: {
  ignored: [/sessions/, /\.ignore/],
}

Per-App Design Checklist

Every new app using this architecture must answer these questions before implementation:

1. Agent Roles

• How many CLI agents? What is each agent's role/persona?
• Do agents interact with each other, the user, or both?

2. Tool Permissions

• What tools does each agent need? List explicitly per agent.
• Which tools are auto-approved (SAFE_TOOLS / --allowedTools)?
• Which tools require human approval via the UI?
• Smoke test: Can each agent actually do its core task with granted permissions?

3. Completion Detection

• How does the system know the interaction is done?
  • Magic string marker? (e.g., NO_MORE_ISSUES, DEBATE_CONCLUDED)
  • Round counter? (after N rounds, stop)
  • User action? (user clicks "End" / "Approve")
• What happens when agents don't emit the expected signal?
  • Heuristic fallback patterns?
  • Timeout with graceful termination?
  • Escalate to user?

4. File System Impact

• Will agents write files? Where?
• Are those directories excluded from the dev server file watcher?
• Are those directories in .gitignore?

5. Turn Management

• How long might a single turn take? Is 300s sufficient?
• Are there intermediate checkpoints where the user should be notified?

Known Bugs Reference

For the symptom-first diagnostic reference (all 13 bugs, organized by what you see), see known-bugs.md.

Generic bugs (affect any WS + CLI app): #1, #2, #3, #4, #5, #8, #10, #12 Project-specific bugs: #6, #7, #9, #11, #13

Supporting Files

• protocol-reference.md — Detailed NDJSON protocol spec with all message types
• known-bugs.md — Symptom-first bug catalog (13 issues) for quick diagnosis
• BUGS_FIXED.md — Full bug catalog with extended analysis and reusability tiers