# Prozessgrenzen

> Welcher Prozess welchen Teil ausführt, wie Aufrufe die Grenzen überqueren, wie Sessions zu Worktrees und Threads stehen, und wo Sie mit dem Lesen des Quellcodes beginnen.

Handbuch / Architektur · Gegen den Quellcode geprüft am 2026-10-05 · https://www.hbcode.ai/de/docs/architecture

## Der Implementierungs-Stack

HB Code hat vier Anwendungsgrenzen und zwei Agent-Prozessgrenzen. Das Desktop-Frontend ist React und TypeScript in einer Tauri-2-WebView. Sein Rust-Backend besitzt lokale Commands, den SQLite-Produktzustand, den entfernten RPC-Router und beide Agent-Prozesse: den Codex-app-server-Kindprozess und den Claude-Agent-Host, einen Node-Prozess, der das Claude Agent SDK ausführt. Eine Session wählt ihren Agenten, wenn sie erstellt wird, und behält ihn. Der Server ist Rust mit Actix Web, Tokio, SQLx für PostgreSQL und Redis-Integration. Die iOS-Begleit-App verwendet Swift und SwiftUI, mit UIKit für ihre Chat-Collection-View, und die Android-Begleit-App verwendet Kotlin und Jetpack Compose. Beide Telefone sprechen denselben RPC-Vertrag mit dem Desktop.

**Die WebView, die Agenten und Ihre Telefone tauschen Daten nur über die Rust-Laufzeit aus**

Innerhalb der gestrichelten Linie liegt Ihr Computer. Die WebView spricht über Tauri-Befehle und -Events mit der Rust-Laufzeit, und der Codex app-server läuft als Kindprozess, der mit der Laufzeit JSON-RPC-Zeilen über stdin und stdout austauscht. Die Laufzeit besitzt appdata.db und liest Projektordner und Git selbst. Neben dem Codex-Kindprozess läuft eine Claude-Session über den Claude-Agent-Host, einen Node-Prozess, den die Laufzeit für jeden Run startet und mit dem sie in JSON-Zeilen über stdin und stdout spricht. Beide Agenten führen Befehle aus und ändern Dateien im Projekt. Codex hält Transkripte und seine ChatGPT-Anmeldung in seinem eigenen Profilverzeichnis und ruft OpenAI auf. Claude hält sie in ~/.claude und ruft Anthropic auf. Jeder Pfeil, der die gestrichelte Linie kreuzt, beginnt innerhalb: Der Desktop öffnet einen WebSocket zum regionalen Server, jedes Telefon öffnet einen eigenen Socket zum selben Relay, und jeder Agent ruft seinen Anbieter über HTTPS auf.

- **Rust-Laufzeit** (chat · agents · remote_api): Bedient die Befehle der WebView und die RPC-Anfragen der Telefone mit denselben Domänendiensten. Sie besitzt appdata.db und liest Projektdateien und Git selbst.
- **Codex app-server** (--listen stdio://): Ein Kindprozess pro Profilpaar, und höchstens drei bleiben aktiv, außer alle sind beschäftigt. Die Laufzeit liest seinen Verlauf über die Pipe mit thread/items/list, nie aus seinen Dateien.
- **Claude-Agent-Host** (desktop/agent-host): Ein Node-Prozess, der das Claude Agent SDK ausführt, das wiederum die claude-Programmdatei startet. Die Laufzeit startet einen Host pro Run und Einmal-Hosts für Lesevorgänge, daher überlebt kein Claude-Prozess seine Arbeit.
- **Regionaler Server** (/ws/device-link): Läuft in den USA oder der EU und reicht Nachrichten zwischen dem Socket, den der Desktop geöffnet hat, und dem Socket jedes Telefons weiter. Er speichert Konten, Gerätezeilen und Präsenz, nie Projektdateien oder Transkripte.

- [Wie sich Codex und Claude eine Chat-Schicht teilen](https://www.hbcode.ai/de/docs/agents.md): Was Codex und Claude teilen, was jedem Adapter gehört und was die Dispatch-Schicht entscheidet.

## Eine mobile Anfrage bis zur Ausführung nachverfolgen

**Eine Telefonanfrage und ein Klick am Desktop rufen denselben Dienst auf**

Zwei Wege enden in einem Dienst. Links durchläuft eine Telefonanfrage zuerst das Relay, das die Methode, den Idempotenzschlüssel und die Verbindung des Desktops prüft. Auf Ihrem Computer wartet die RPC-Annahme auf einen freien Platz, gleicht das Konto ab, sucht den Idempotenzschlüssel und dekodiert die Parameter. Rechts durchläuft ein Klick in der WebView nur die Tauri-Prüfung, ob sein Fenster den Befehl aufrufen darf, und das Dekodieren seiner Argumente. Beide Wege münden in submit_outbox_request, das für jeden Aufrufer drei Prüfungen ausführt: Text oder Anhänge, ein gültiger Sendemodus und eine Fähigkeit, die der Agent der Session hat. Dann speichert es die Nachricht und gibt eine Quittung zurück. Später übergibt ein Drain-Task die Nachricht an agents/dispatch, das den Turn im Agenten der Session startet: im Codex-Kindprozess oder in einem Claude-Agent-Host.

- **Relay** (request_validation.rs): Prüft den Methodennamen und den Idempotenzschlüssel und überlässt die Parameter dem Desktop, außer bei session.syncHistoryState. Ist der Desktop offline oder verbindet er sich neu, antwortet das Relay selbst mit -32010 oder -32011.
- **RPC-Annahme** (snapshot_and_rpc.rs · router): Läuft für jede Telefonanfrage: 8 leichte und 2 schwere Plätze, dann der Kontoabgleich. Eine Mutation nimmt einen dauerhaften Idempotenzanspruch, und der Adapter dekodiert die Parameter in einen Anfragetyp, der unbekannte Felder ablehnt.
- **Tauri-Befehl** (capabilities/default.json): Erlaubt dem Hauptfenster und den Session-Fenstern, Workspace-Befehle aufzurufen. Tauri dekodiert die Argumente in denselben Anfragetyp, daher scheitern unbekannte Felder auch hier.
- **Outbox-Dienst** (submit_outbox_request): Beide Wege rufen ihn auf, daher gelten seine Regeln für jeden Aufrufer, und eine wiederholte operationId legt nie eine zweite Nachricht an. Er lehnt das Ersetzen einer gesendeten Nachricht oder einen Geschwindigkeitsmodus in einer Claude-Session ab. Er speichert die Nachricht und gibt die Quittung zurück, und ein Drain-Task startet den Turn später.

Belassen Sie Geschäftsregeln im Domänendienst, wo sich beide Wege treffen. Der Dienst lehnt auch ab, was der Agent der Session nicht kann: das Ersetzen einer gesendeten Nachricht oder einen Geschwindigkeitsmodus in einer Claude-Session. Die gespeicherte Nachricht nennt keinen Agent-Prozess. Ein Drain-Task übergibt sie später an agents/dispatch, das den Turn im Codex-app-server-Kindprozess oder in einem neuen Claude-Agent-Host startet. Übereinstimmende UI-Bedienelemente sind keine Autorisierungsprüfung. Das Relay antwortet außerdem mit -32012, wenn ein Desktop eine Anfrage nicht vor dem Timeout des Relays abschließt, und das Relay-Kapitel listet seine Codes und Timer.

## Projekte, Worktrees und Sessions

**Nur ein eigener Worktree hält die Dateien zweier Aufgaben auseinander**

Drei Geräte wählen ihre Sessions selbst. Der Desktop und das iPhone zeigen dieselbe Session Dunkelmodus, das Android-Telefon zeigt Login-Fix. Einstellungsseite und Dunkelmodus arbeiten im Haupt-Worktree und bearbeiten beide dessen src/settings.tsx, ohne Sperre zwischen ihnen. Login-Fix und sein Subagent-Thread Regressionstest arbeiten im verknüpften Worktree, einem getrennten Checkout mit eigener Kopie von src/settings.tsx. Beide Worktrees gehören zu einem Projekt. Wird ein verknüpfter Worktree gelöscht, verschiebt der nächste Scan seine ruhenden Sessions in den Haupt-Worktree und überspringt laufende.

- **Worktree** (git worktree list): HB Code listet die vorhandenen Worktrees auf und legt nie einen an. Eine Session entsteht in einem davon, und der Desktop lehnt ein projectDirectory ab, das kein Worktree des Projekts ist.
- **Subagent-Thread** (activeRun: null): Vom Agenten während eines Turns der Eltern-Session gestartet, in deren Worktree. Er hat eine eigene Timeline und ein eigenes Live-Overlay, und nur die Eltern-Session meldet den aktiven Run.
- **Geräteauswahl** (appSessionId): Jedes Gerät wählt Projekt, Worktree und Session selbst, daher können zwei Geräte dieselbe Session oder verschiedene zeigen. Ein Subagent-Thread wird über seine Session geöffnet.

Ein Projekt ist ein Git-Repository, gruppiert unter seinem Haupt-Worktree. Ein Ordner ohne Git ist ein Projekt, dessen einziger Arbeitsbereich der Ordner selbst ist.

## Im Quellcode-Baum navigieren

| Pfad vom Repository-Stammverzeichnis | Beginnen Sie hier für |
| --- | --- |
| desktop/src/app/components/workspace-chat/ | React-Workspace-Komposition, Timeline-Zustand, Viewport-Ownership und Outbox-Anzeige. |
| desktop/src-tauri/src/commands/ | Tauri-Einstiegspunkte und Desktop-Domänenoperationen. |
| desktop/src-tauri/src/chat/ | Die gemeinsame Chat-Schicht: Outbox, Operation-Ledger, Run-Registry, Live-Timeline-Overlay, Darstellungszeilen und die Tauri-Einstiegspunkte des Chats. Sie importiert nie einen Agent-Adapter. |
| desktop/src-tauri/src/agents/codex/ | Der Codex-Adapter: app-server-Kindprozess, Auth-Profile, Turns, Verlauf über thread/items/list und der Speicher für Befehlsausgaben. |
| desktop/src-tauri/src/agents/claude/ | Der Claude-Adapter: Run-Schleife, Projektion in die gemeinsamen Zeilen, Verlauf, Subagents, Berechtigungen, Konten und die Laufzeit des Agent-Hosts. |
| desktop/src-tauri/src/agents/dispatch/ | Der Code, der den Adapter einer Session auswählt. Die Chat-Schicht erreicht einen Adapter nur über dieses Modul. |
| desktop/src-tauri/src/usage_history/ | Gespeicherte Plan-Limit-Messwerte beider Agenten. Es liest beide Adapter direkt, weil es beide Kontoarten liest. |
| desktop/src-tauri/src/services/agent_tools/ | Der HB-Code-Tool-Katalog, den beide Agenten bekommen, und die Tool-Handler. |
| desktop/agent-host/ | Der Node-Agent-Host in TypeScript. Er führt das Claude Agent SDK aus und spricht JSON-Zeilen über stdin und stdout. |
| desktop/src-tauri/src/remote_api/ | RPC-Typen, Validierung, Idempotenz, Dispatch und Remote-Methodenadapter. |
| server/src/services/device_link_ws/ | WebSocket-Registrierung, Anforderungsvalidierung, Weiterleitung und Verbindungslebenszyklus. |
| mobile/ios/Core/Sources/Core/Connectivity/Relay/ | iOS-Relay-Verbindung und Methodenvertrag. |
| mobile/ios/VibeUI/Sources/VibeUI/Features/Workspace/Chat/ | iOS-Chat-Ownership, Timeline-Reconciliation und Collection-Rendering. |
| mobile/android/app/src/main/java/com/hbcode/mobile/ | Android-Einstiegs-Routing, Workspace-Tabs, Relay-Client und Compose-Bildschirme. |

- [Wie sich Codex und Claude eine Chat-Schicht teilen](https://www.hbcode.ai/de/docs/agents.md#layers): Die Importregel zwischen chat, dispatch und den beiden Adaptern sowie eine Zeile pro dispatch-Datei.
- [Die Codex-app-server-Integration](https://www.hbcode.ai/de/docs/codex-app-server.md): Der Kindprozess, die JSON-RPC-Pipe, die Tool-Injektion und profilgebundene Clients.
- [Die Claude-Agent-SDK-Integration](https://www.hbcode.ai/de/docs/claude-agent-sdk.md): Der Agent-Host-Prozess, die Verlaufsprojektion, Live-Runs, Subagents und Konten.
- [Nachrichtenzustellung](https://www.hbcode.ai/de/docs/message-delivery.md): Verfolgen Sie eine Operation von der dauerhaften Verwahrung bis zu einem laufenden Turn.
- [Speichereigentum](https://www.hbcode.ai/de/docs/storage.md): Datenbankeigentum und die Quellidentität von Konversationen.