Die Claude-Agent-SDK-Integration
Wie der Desktop Claude über einen Node-Agent-Host ausführt: die Pipe mit JSON-Zeilen, die Projektion von Claude-Nachrichten in die gemeinsamen Timeline-Zeilen, Live-Runs und Freigaben, Subagents und Konten.
Gegen den Quellcode geprüft am 29. September 2026
Auf dieser Seite
Der Agent-Host-Prozess
Claude läuft über den Agent-Host, ein kleines TypeScript-Programm in desktop/agent-host, das @anthropic-ai/claude-agent-sdk verwendet. Der Desktop startet ihn mit Node und übergibt den Pfad der mitgelieferten Claude-Programmdatei als einziges Argument. Ein Entwicklungs-Build führt node aus dem PATH mit agent-host/dist/src/entry.js aus. Eine paketierte App führt ihr mitgeliefertes node mit claude/host/entry.mjs aus ihren Ressourcen aus.
Beide Seiten tauschen ein JSON-Objekt pro Zeile über stdin und stdout aus. Eine Anfrage trägt eine id, und ihre Antwort trägt dieselbe id mit einem result oder einem error. Eine Zeile ohne id ist ein Event: message, permission, permissionResolved, failed oder closed. Der Host prüft jede Anfrage gegen ein strenges Schema, daher schlägt ein unbekanntes Feld fehl. Der Desktop gibt jeder Anfrage 35 Sekunden.
| Anfrage | Was der Host tut |
|---|---|
| open | Startet eine SDK-Query für die Session in ihrem Projektordner. Sie setzt die Unterhaltung fort, wenn Claude ein gespeichertes Transkript für diese id hat, und startet sonst eine neue mit dieser id. Ein Host besitzt höchstens eine Session. |
| send | Schreibt die Nachricht mit der Nachrichten-id des Desktops in die offene Query. Solange Claude noch arbeitet, lehnt er ab. |
| permission | Beantwortet eine ausstehende Tool-Berechtigung mit allow oder deny. |
| interrupt, close | Stoppt den Turn oder schließt die Query und beendet den Host. |
| history, list, inspect | Liest gespeicherte Unterhaltungen des Ordners über das SDK. |
| subagents, subagentHistory, toolOutput | Liest gespeicherte Subagent-Transkripte und die vollständige Ausgabe eines Tool-Aufrufs. |
| catalog, usage, title | Liest die Modellliste, die Plan-Nutzung oder einen kurzen Session-Titel. |
Jeder Run bekommt einen neuen Host, und der Host überlebt seinen Run nie. Wenn der Run endet, sendet der Desktop close, schließt stdin und wartet bis zu 10 Sekunden. Danach beendet er die ganze Prozessgruppe des Hosts. Lesevorgänge, die keine offene Unterhaltung brauchen, etwa der Modellkatalog oder ein Titel, laufen in einem eigenen Einmal-Host. Vor dem Start entfernt der Desktop neun Umgebungsmarker, die eine übergeordnete Claude-Code-Session ihren Kindern gibt, darunter CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID und CLAUDE_PID. Ein Desktop, den Sie aus Claude Code heraus starten, würde seine Sessions sonst als Kind-Sessions ausführen, und Claude speichert deren Transkripte nicht.
Die Query lädt Benutzer-, Projekt- und lokale Einstellungen, verwendet den Systemprompt claude_code und speichert die Session. Der Host setzt CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS, weil ein Turn, der Subagents im Hintergrund startet, vor ihnen endet. Nur der Zustand idle sagt dem Host, dass der ganze Run vorbei ist.
Verlauf und die gemeinsamen Timeline-Zeilen
Der Desktop liest Claudes Transkriptdateien nie selbst. Der Host liest sie mit getSessionMessages und gibt Seiten mit höchstens 100 vollständigen Nachrichten zurück. Er fügt die SDK-Umschläge einer API-Nachricht zu einer Nachricht zusammen und verwirft Nachrichten, die nichts zu zeigen haben. Eine Seitengrenze ist eine Nachrichten-uuid, und wenn diese Nachricht fehlt, bittet die Antwort den Desktop, neu zu laden. Das SDK liefert eine komprimierte Unterhaltung erst ab ihrer letzten Komprimierung, deshalb erscheinen ältere Turns einer solchen Unterhaltung nicht in HB Code. Die vollständige Ausgabe eines Befehls wird bei Bedarf über toolOutput gelesen, so wie eine Codex-Protokollausgabe.
Um eine bestehende Claude-Code-Unterhaltung fortzusetzen, listet der Desktop die gespeicherten Unterhaltungen genau dieses Workspace-Ordners, die neueste zuerst. Eine Unterhaltung gehört zu höchstens einer HB-Code-Session. Wählen Sie sie erneut, öffnet sich diese Session statt einer zweiten.
Der Claude-Adapter projiziert jede Nachricht in dieselben Timeline-Zeilen, die Codex verwendet. Eine Live-Zeile und ihre gespeicherte Zeile nehmen ihre Identität aus der API-Nachrichten-id oder der gespeicherten uuid, daher ersetzt die gespeicherte Zeile die Live-Zeile an derselben Stelle.
| Claude-Nachricht oder -Block | Timeline-Zeile |
|---|---|
| Bash-Tool-Aufruf und sein Ergebnis | Eine Befehlszeile mit ihrer Ausgabe. Die Ausgabezeile nennt das gespeicherte Ergebnis, das erst gelesen wird, wenn Sie es öffnen. |
| Edit, MultiEdit, Write, NotebookEdit | Eine Dateiänderungszeile. Claude liefert den alten und den neuen Text, daher baut der Adapter den Unified Diff. Jeder Hunk hat einen bloßen @@-Kopf, weil Claude keine Zeilennummern liefert. |
| Read | Eine Tool-Zeile mit dem Dateinamen als Titel. Ihr Detail zeigt den Dateitext und öffnet die Datei. |
| Jedes andere Tool | Eine Zeile, die ihr Ergebnis an derselben Stelle abschließt: Tool call, dann Tool output, Tool error oder Tool declined. Sie zeigt eine lesbare Bezeichnung, und ein MCP-Tool erscheint als „server: tool“. |
| TodoWrite, EnterPlanMode, ExitPlanMode | Ein Plan mit seinen Schritten oder eine Plan-Eventzeile mit dem Plan als Markdown. |
| Bild in einem Tool-Ergebnis | Eine Bildzeile nach der Tool-Zeile. |
| Thinking | Eine Reasoning-Zeile. Leeres Thinking erzeugt keine Zeile. |
| Unterbrechungshinweis | Eine Markierung für einen abgebrochenen Turn. |
| Komprimierungszusammenfassung | Eine Markierung „Conversation compacted“. |
| Lokaler Slash-Befehl | Sein Name und seine Ausgabe. Terminal-Verwaltung wie /exit ist ausgeblendet. |
| Nachricht eines anderen Agenten | Eine Zeile für Agentenkommunikation. |
| Antwort, die Claude selbst schreibt, etwa ein Nutzungslimit oder ein API-Fehler | Eine Systemzeile. |
| Synthetische Benutzernachricht (isSynthetic) und andere Meta-Zeilen | Ausgeblendet. |
| Spawn-Aufruf eines Subagents | Eine Spawn-Zeile mit dem Status des Subagents und einem Link zu seiner eigenen Ansicht. |
Live-Runs, Freigaben und Fehler
agents/dispatch sendet eine Nachricht aus der Queue an den Adapter des Agenten der Session. Eine Claude-Session kann einen laufenden Turn nicht steuern, den letzten Turn nicht ersetzen und keinen Geschwindigkeitsmodus nutzen. Eine Steer-Anfrage wird abgelehnt, bevor sie den Host erreicht, daher wartet eine Nachricht in der Queue oder geht raus, nachdem Sie den Run stoppen. Eine Session hat jeweils einen aktiven Claude-Run.
Der Run öffnet den Host mit Modell, Effort und Berechtigungsmodus der Session, speichert die Operation und sendet dann den Text. Claudes Live-Stream wiederholt den Prompt nie, und ein Schreibvorgang auf stdin oder ein Delta ist nie ein Zustellnachweis. Claude speichert die Benutzernachricht, bevor es das Modell aufruft. Deshalb startet der erste Frame nach send einen Transkript-Lesevorgang, und ein Frame, der die Nachricht in user_message_uuid nennt, startet einen weiteren, wenn der erste zu früh kam. Findet ein Lesevorgang die Nachricht, erscheint zuerst die gespeicherte Zeile, und danach verschwindet die Outbox-Zeile. Am Ende des Runs ist ein weiterer Lesevorgang der endgültige Nachweis, auch für einen gestoppten oder fehlgeschlagenen Run. Eine Nachricht, die kein Lesevorgang findet, wird nie automatisch erneut gesendet.
| Zugriffsstufe | Claude-Berechtigungsmodus |
|---|---|
| read-only | plan |
| full-auto | acceptEdits |
| full-access | auto. open schlägt fehl, wenn das Modell den Auto-Modus nicht unterstützt. |
| unrestricted | bypassPermissions |
Wenn Claude ein Tool verwenden will, hält der Host das canUseTool-Promise des SDK und sendet ein permission-Event. Der Desktop zeigt dieselbe Freigabekarte wie für Codex, mit Accept und Decline. Ein Bash-Aufruf ist eine Befehlsfreigabe, und die Anfrage eines Subagents nennt den Subagent. Ein Telefon antwortet über run.chatResolveApproval, und der Dispatch lässt den Claude-Adapter zuerst antworten, wenn er diese Anfrage-id hält. Ein Stopp lehnt jede offene Anfrage mit „Run stopped.“ ab, und das Ende des Runs markiert die übrigen Karten als abgebrochen. AskUserQuestion ist ausgeschaltet, und Claude stellt seine Fragen in der Chat-Antwort.
Ein fehlgeschlagener Run behält seinen Grund im Fehlerprotokoll des Desktops unter claude_run, mit den ids von Session, Run und Operation. Paketierte Apps verwerfen die Standardfehlerausgabe, daher ginge die Logzeile allein verloren. Der Grund stammt aus Claudes errors-Liste oder, bei API-Fehlern wie einer fehlenden Anmeldung, aus seinem result-Text.
Subagents als Kind-Threads
Claude-Subagents verwenden dieselben Listen-, Timeline- und Live-Pfade wie Codex-Kind-Threads. Während eines Runs meldet Claude jeden Subagent über Task-Events und leitet seine Turns mit der id des startenden Tool-Aufrufs weiter. Der Adapter schickt diese Turns in die eigene Ansicht des Subagents, und der Parent zeigt eine Spawn-Zeile. Ein Subagent, den die Unterhaltung gestartet hat, hat Tiefe 1, und jede Verschachtelung addiert 1.
Nach dem Run sind die gespeicherten Transkripte die einzige Quelle. Der Host liest sie mit getSubagentMessages, und ein fertiges Transkript wird einmal pro Desktop-Lauf gelesen. Subagents, die beim Ende des Runs noch offen sind, stoppen mit ihm.
Konten und Nutzung
Das Standardkonto ist die Claude-Anmeldung dieses Computers und läuft mit Claudes eigenem Ordner. Jedes hinzugefügte Konto ist ein Claude-Ordner in den Anwendungsdaten von HB Code. Es behält seine eigene Anmeldung und verlinkt jeden anderen Eintrag auf den Hauptordner. Alle Konten lesen und fortsetzen daher dieselben Sessions mit denselben Einstellungen, und ein Wechsel ändert nur, wer für einen Turn bezahlt. Der nächste Turn läuft mit dem aktiven Konto, und ein Konto bleibt, solange ein laufender Turn es verwendet.
HB Code führt Claudes eigene Anmeldebefehle für einen Kontoordner aus. Es liest nie ein Token und führt keinen eigenen Autorisierungsablauf aus. Die Nutzung kommt aus dem SDK: das rollierende Fünf-Stunden-Fenster und die Wochenfenster. Das Wochenfenster für Drittanbieter-Apps bleibt außen vor. Ein Konto mit API-Schlüssel hat keine Plan-Fenster. Die Seitenleiste, die Einstellungsseite und die Telefone teilen sich eine Messung pro Konto und Minute, und ein beendeter Run verwirft die Messung dieses Kontos.