Claude Code & WebSockets: Echtzeit-Kommunikation in Python und JavaScript

HTTP kennt nur eine Richtung: Client fragt, Server antwortet — und die Verbindung ist weg. Für Dashboards, Chats, Kollaborationstools oder Live-Notifications reicht das nicht. WebSockets lösen dieses Problem mit einer dauerhaften, bidirektionalen Verbindung zwischen Client und Server. Dieser Artikel zeigt, wie du mit Claude Code einen vollständigen WebSocket-Stack in Python und JavaScript aufbaust — vom Handshake bis zur Reconnect-Logik.

Das Besondere an Claude Code für WebSocket-Entwicklung: Es generiert nicht nur den Boilerplate, sondern versteht den Zustandskontext einer persistenten Verbindung. Race Conditions beim Broadcasting, korrekte Cleanup-Logik beim Disconnect, Token-Validierung vor dem Upgrade — all das bekommt Claude Code auf einmal im Blick, weil es die gesamte Codebasis liest.

1. WebSockets vs. HTTP: Was ist der Unterschied?

HTTP ist zustandslos und request-getrieben: jede Interaktion öffnet eine neue Verbindung, überträgt Daten und schließt wieder. Für WebSockets gilt das nicht. Der Verbindungsaufbau beginnt zwar mit einem HTTP-Request — dem WebSocket Handshake — aber danach bleibt der TCP-Socket offen und beide Seiten können jederzeit Nachrichten senden, ohne dass die andere Seite fragen muss.

Das Protokoll ist vollduplex: Server und Client sprechen gleichzeitig, unabhängig voneinander. Ein HTTP-Server, der Push-Nachrichten simulieren will, braucht dafür Tricks wie Long Polling oder Server-Sent Events — mit WebSockets ist Push nativ.

• HTTP: Request/Response, Connection: close, zustandslos, unidirektional
• WebSocket: Persistente Verbindung, bidirektional, geringer Overhead pro Nachricht
• Handshake: HTTP GET mit Upgrade: websocket → Server antwortet mit 101 Switching Protocols

2. Server in Python: websockets-Library und FastAPI

Zwei verbreitete Wege in Python: die schlanke websockets-Library oder FastAPI mit eingebautem WebSocket-Support. Claude Code generiert beide Varianten korrekt — inklusive der async-Struktur, die WebSocket-Server zwingend brauchen.

Einfacher Server mit der websockets-Library

claude "Schreibe einen WebSocket-Server mit der Python websockets-Library.
Der Server soll Nachrichten von verbundenen Clients empfangen und
an alle anderen verbundenen Clients weiterleiten (Broadcasting).
Alle verbundenen Clients in einem Set verwalten."

Claude Code generiert daraus einen vollständigen, lauffähigen Server:

import asyncio
import websockets

CLIENTS: set = set()

async def handler(websocket):
    CLIENTS.add(websocket)
    try:
        async for message in websocket:
            websockets.broadcast(CLIENTS - {websocket}, message)
    finally:
        CLIENTS.discard(websocket)

async def main():
    async with websockets.serve(handler, "localhost", 8765):
        await asyncio.Future()  # run forever

asyncio.run(main())

WebSocket-Endpoint in FastAPI

Wer FastAPI bereits einsetzt, bekommt WebSockets ohne zusätzliche Abhängigkeit:

from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from typing import List

app = FastAPI()

class ConnectionManager:
    def __init__(self):
        self.active: List[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            data = await ws.receive_text()
            await manager.broadcast(data)
    except WebSocketDisconnect:
        manager.disconnect(ws)

3. Client in JavaScript: die native WebSocket API

Browser haben eine eingebaute WebSocket-Klasse — keine Library nötig. Claude Code generiert den Client zusammen mit dem Server und achtet dabei darauf, dass Event-Handler korrekt registriert und entfernt werden:

const ws = new WebSocket("ws://localhost:8765");

ws.addEventListener("open", () => {
  console.log("Verbunden");
  ws.send(JSON.stringify({ type: "join", user: "Alice" }));
});

ws.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);
  renderMessage(data);
});

ws.addEventListener("close", (event) => {
  console.log(`Verbindung getrennt: ${event.code} ${event.reason}`);
});

ws.addEventListener("error", (error) => {
  console.error("WebSocket-Fehler:", error);
});

function sendMessage(text) {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: "message", text }));
  }
}

Wichtig: ws.readyState prüfen, bevor man sendet. Ein send() auf einer noch nicht geöffneten oder bereits geschlossenen Verbindung wirft einen Fehler. Claude Code fügt diese Prüfung automatisch ein, wenn du den Prompt entsprechend formulierst.

4. Rooms und Broadcasting: mehrere Clients koordinieren

In der Praxis braucht man selten globales Broadcasting — meistens sollen Nachrichten nur an Clients in einem bestimmten Raum gehen. Claude Code generiert die Room-Logik auf Prompt hin:

claude "Erweitere den FastAPI WebSocket-Server um Room-Support.
Clients sollen beim Verbinden einen room_id-Parameter übergeben.
Nachrichten werden nur innerhalb desselben Rooms verteilt."

Das Ergebnis: ein Dictionary, das Room-IDs auf Sets von WebSocket-Verbindungen abbildet, mit sauberem Cleanup beim Disconnect. Für produktiven Einsatz empfiehlt Claude Code hier meist Redis als Backend — damit Broadcasting auch über mehrere Server-Instanzen hinweg funktioniert.

5. Authentifizierung bei WebSocket-Verbindungen

WebSockets unterstützen keine Custom-Header beim initialen Handshake vom Browser aus. Das übliche Muster: Token im Query-Parameter oder im ersten Nachrichtenframe nach dem Verbindungsaufbau.

claude "Füge JWT-Authentifizierung zum WebSocket-Endpoint hinzu.
Der Client übergibt das Token als Query-Parameter token=...
Der Server validiert das Token vor dem ws.accept() und trennt
die Verbindung mit Code 4001 bei ungültigem Token."

from fastapi import WebSocket, Query
from jose import jwt, JWTError

SECRET = "dein-secret"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, token: str = Query(...)):
    try:
        payload = jwt.decode(token, SECRET, algorithms=["HS256"])
        user_id = payload["sub"]
    except JWTError:
        await ws.close(code=4001)
        return

    await manager.connect(ws, user_id)
    # ... rest des Handlers

6. Fehlerbehandlung: Reconnect-Logik und Heartbeat

WebSocket-Verbindungen reißen ab — durch Netzwerkunterbrechungen, Server-Neustarts oder Proxy-Timeouts. Ein produktionsreifer Client reconnectet automatisch:

function createWebSocket(url) {
  let ws;
  let retryDelay = 1000;
  const MAX_DELAY = 30000;

  function connect() {
    ws = new WebSocket(url);

    ws.addEventListener("open", () => {
      retryDelay = 1000; // Reset nach erfolgreicher Verbindung
      startHeartbeat();
    });

    ws.addEventListener("close", () => {
      console.log(`Reconnect in ${retryDelay / 1000}s`);
      setTimeout(connect, retryDelay);
      retryDelay = Math.min(retryDelay * 2, MAX_DELAY); // Exponential backoff
    });

    ws.addEventListener("message", handleMessage);
  }

  let heartbeatInterval;
  function startHeartbeat() {
    heartbeatInterval = setInterval(() => {
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: "ping" }));
      }
    }, 25000);
  }

  connect();
  return { send: (msg) => ws?.readyState === WebSocket.OPEN && ws.send(msg) };
}

Serverseitig muss der Ping-Pong ebenfalls implementiert werden. Die websockets-Library in Python hat eingebauten Ping/Pong-Support über den ping_interval-Parameter. FastAPI delegiert das an starlette, das seinerseits auf das websockets-Paket aufbaut — hier muss man Timeouts explizit konfigurieren.

7. Claude Code Tipps: WebSocket-Server generieren und debuggen

WebSocket-Debugging ist notorisch schwierig, weil der Traffic nicht im normalen HTTP-Tab der DevTools erscheint. Drei Methoden, die Claude Code empfiehlt:

• Chrome DevTools → Network → WS: Zeigt alle Frames einer WebSocket-Verbindung — gesendet (grau) und empfangen (weiß). Klick auf eine Verbindung, dann Tab „Messages“.
• wscat im Terminal: npx wscat -c ws://localhost:8765 — interaktiver WebSocket-Client für schnelle Tests ohne Browser.
• Claude Code direkt: Fehlermeldungen aus dem Server-Log übergeben, Claude Code findet den Disconnect-Grund und schlägt den Fix vor.

claude "Mein WebSocket-Server trennt Verbindungen nach ca. 60 Sekunden
Inaktivität. Das passiert auch wenn Clients aktiv sind. Hier ist der
Server-Log: [Log einfügen]. Was ist die Ursache?"

In den meisten Fällen liegt das an einem vorgelagerten Proxy (nginx, AWS ALB), der Idle-Connections schließt. Claude Code erkennt das Muster im Log und liefert die nginx-Konfiguration, die das Problem löst: proxy_read_timeout 3600s; und proxy_send_timeout 3600s;.

Claude Code versteht WebSocket-Protokolldetails — Close-Codes, Frame-Typen, Ping/Pong-Sequenzen. Wenn du den Close-Code aus dem close-Event übergibst, erklärt es dir exakt, was passiert ist und auf welcher Seite der Fehler lag.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code für Python-Projekte — Projektstruktur, virtuelle Umgebungen, Test-Workflows
• Claude Code Debugging — Stack Traces, Log-Analyse, Root-Cause-Suche