# Browser Bridge: Der Agent arbeitet in Ihrem Chrome

> Eine Manifest-V3-Erweiterung, ein Native-Messaging-Host und Chrome-DevTools-Eingaben lassen den Agenten in Ihrem eigenen Browser suchen, lesen, klicken, tippen, hochladen und Screenshots machen, sichtbar und innerhalb von Grenzen.

Handbuch / Mitgelieferte Tools · Gegen den Quellcode geprüft am 2026-10-05 · https://www.hbcode.ai/de/docs/tools/browser-bridge

## Wie die Bridge funktioniert

**Browser-Befehle warten auf dem Desktop, bis Chrome sie abfragt**

Die Zeit läuft von links nach rechts über den Agentenprozess, die Desktop-Laufzeit, den nativen Host, die Erweiterung und die Seite. Die Erweiterung fragt über einen nativen Host, den Chrome startet, immer wieder nach Arbeit, und der Desktop hält jede Frage bis zu 25 Sekunden. Ein Tool-Aufruf von Codex oder Claude wird eingereiht, der wartenden Frage übergeben und über das DevTools Protocol in der Seite ausgeführt, und sein Ergebnis wandert zurück nach oben und schließt den Aufruf ab.

- **Tool-Aufruf** (item/tool/call · toolCall): Der Agent bittet den Desktop, use_user_browser auszuführen. Codex sendet die Anfrage item/tool/call, und der Claude-Host sendet das Ereignis toolCall. Der Desktop prüft Upload-Pfade, reiht den Befehl ein und wartet 60 Sekunden, bei status 5 Sekunden. Kommt rechtzeitig kein Ergebnis, erhält der Agent einen Tool-Fehler, der dazu auffordert, die Erweiterung zu installieren und Chrome geöffnet zu lassen.
- **Long-Poll** (hbcode.next): Die Erweiterung fragt jeweils nach einem Befehl. Der Desktop antwortet nach 25 Sekunden mit command: null, und die Erweiterung fragt sofort erneut. Ein Keep-alive alle 20 Sekunden und ein Wiederverbindungsalarm alle 30 Sekunden halten sie am Fragen, daher lauscht der Desktop nie an einem Netzwerkport.
- **Nativer Host** (hbcode-browser-bridge-host): Chrome startet ihn für com.hbcode.browser_bridge. Er weist einen Erweiterungsursprung außerhalb der veröffentlichten und der Entwicklungs-ID sowie HBCODE_CHROME_EXTENSION_ORIGINS aus seiner eigenen Umgebung ab, hängt das Geheimnis pro Installation an jede Nachricht und öffnet pro Nachricht eine Socket- oder Pipe-Verbindung.
- **Ergebnis** (hbcode.result): Frames von Chrome dürfen 64 MiB erreichen, und Frames an Chrome enden bei 1 MiB. Große Ergebnisse passen also auf dem Weg nach oben, und Befehle bleiben auf dem Weg nach unten klein. Der Desktop schreibt einen Screenshot in eine Datei und gibt dem Agenten Text, Markdown und den Pfad.

Codex- und Claude-Sessions nutzen dasselbe Browser-Tool, use_user_browser, und denselben Desktop-Handler. Ein Codex-Aufruf trifft als Anfrage item/tool/call ein. Ein Claude-Aufruf trifft als Host-Ereignis toolCall ein.

- [Wie die Tool-Liste jeden Agenten erreicht](https://www.hbcode.ai/de/docs/tools/agent-tools.md#overview): Wann jeder Agent die Liste bekommt und wie der Desktop die Session eines Aufrufs findet.

Der Desktop erlaubt die veröffentlichte Chrome-Web-Store-Erweiterungs-ID und die feste Entwicklungs-ID aus dem entpackten Manifest, und HBCODE_CHROME_EXTENSION_ORIGINS ergänzt dieses Manifest um weitere vertrauenswürdige Ursprünge. Der Host akzeptiert sie nur, wenn dieselbe Variable in seiner eigenen Umgebung gesetzt ist. Das IPC-Geheimnis pro Installation liegt in einer mit Modus 0600 angelegten Datei. Der Host wird registriert, wenn die Browser-Bridge-Einstellung eingeschaltet ist, was sie standardmäßig nicht ist, und HBCODE_DISABLE_BROWSER_BRIDGE=1 erzwingt aus. Chrome 120 ist das Minimum, und die Erweiterung umfasst Inkognito-Fenster, damit Recherche dort laufen kann.

| Frist | Wert |
| --- | --- |
| Befehl | 60 Sekunden; status 5 Sekunden. |
| Long-Poll der Erweiterung auf den nächsten Befehl | Kehrt nach 25 Sekunden leer zurück. |
| IPC-Verbindung / Antwort | 5 Sekunden / 35 Sekunden. |
| Lesen einer IPC-Anfrage auf dem Desktop | 10 Sekunden. |
| Eintrag eines eigenen Tabs | 30 Minuten, bei jeder Nutzung erneuert, von einem 30-Sekunden-Alarm aufgeräumt. |

Jede DevTools-Aktion hängt chrome.debugger (Protokoll 1.3) an und löst es danach wieder, sodass Chrome pro Befehl sein Debugging-Banner zeigt. Ein Klick führt zuerst ein injiziertes Locate-Skript aus, um einen Dokumentpunkt zu finden, und sendet dort dann einen DevTools-Klick; Tippen fokussiert zuerst das Ziel und fügt Text über das Protokoll ein. Deshalb funktionieren sie auf Seiten, die synthetische DOM-Events ignorieren; inputMode=dom existiert für Seiten, die den alten Pfad brauchen, und select, check und scroll bleiben injizierte DOM-Aktionen. Die Extraktion wartet, bis die Seite geladen ist und das DOM ruhig wird, standardmäßig 800 Millisekunden Ruhe innerhalb eines Bereitschaftsfensters von 8 Sekunden, das sich auf 30 Sekunden dehnen kann, liest dann das gerenderte sichtbare DOM einschließlich offener Shadow-Roots und Frame-Inhalte und liefert Titel, URL, Text, eine Leseansicht, Markdown, Links, Überschriften, Frame-Metadaten und Warnungen.

## Browser Bridge aktivieren

1. Installieren Sie die HB-Code-Browser-Bridge-Erweiterung aus dem Chrome Web Store. Für die Entwicklung laden Sie den entpackten Ordner desktop/browser-extension.
2. Öffnen Sie in HB Code Settings → Connections.
3. Schalten Sie in der Karte Browser Bridge die Option Enable Browser Bridge ein. Der Desktop speichert die Änderung, startet den IPC-Server und registriert den Native-Messaging-Host. Sie müssen HB Code nicht neu starten.

## Was der Agent tun kann

| Aktion | Verhalten |
| --- | --- |
| status | Liefert den aktiven Tab und ein Inventar jedes offenen Tabs in jedem Fenster mit URL und Titel sowie eigene Browser-Arbeitsbereiche und Fenster, damit spätere Aufrufe bekannte IDs ansteuern können. Ohne verbundene Erweiterung liefert es stattdessen Bridge-Diagnosen: Hostname, IPC-Endpunkt, erlaubte Erweiterungs-IDs, aufgelöstes Host-Binary und Installationsziele des Manifests. |
| search, open, extract | Search öffnet eine sichtbare Google-Ergebnisseite und liefert klassifizierte Treffer. Open und extract nehmen eine URL an und können einen neuen Tab, den aktuellen Tab oder eine explizite Tab-ID verwenden, und extract kann vor dem Lesen auf einen Selektor, einen Text oder ein URL-Fragment warten. |
| click, type, press, select, check | Lokatoren akzeptieren einen CSS-Selektor, sichtbaren Text, Rolle plus barrierefreien Namen, Label, Platzhalter, eine Frame-ID aus extract oder inspect oder Koordinaten im Viewport- oder Dokumentraum. Check ist idempotent und meldet den endgültigen Zustand. |
| upload | Weist einem lokalisierten Dateieingabefeld über das DevTools-Protokoll bis zu 20 absolute lokale Dateipfade zu. Der Desktop prüft zuerst, dass jeder Pfad absolut, kein Symlink und eine lesbare reguläre Datei ist, kanonisiert ihn und weist Komponenten wie .ssh, .gnupg, keychains, cookies, id_rsa, .env, .pem, .key, private_key, secret und token zurück. Es gibt absichtlich keine Bytegrenze, kein Dateiinhalt gelangt ins Transkript, und geschützte Chrome-Seiten können es blockieren. |
| scroll, wait, inspect | Wait deckt Bedingungen für Laden, Selektor, Text, Rolle, Label, Platzhalter und URL ab. Inspect listet interaktive Elemente vor einem Klick, wenn die Seitenstruktur unklar ist. |
| screenshot | Erfasst standardmäßig die ganze Seite über das DevTools-Protokoll, oder den Viewport oder ein Ausschnittrechteck, als JPEG mit Qualität 70. Eine geschützte Seite liefert full_page_screenshot_unavailable statt eines stillen Viewport-Bildes. Der Desktop schreibt das dekodierte Bild mit Modus 0600 unter das Cache-Verzeichnis in hbcode/browser-screenshots und gibt den Pfad zurück; nichts löscht diese Dateien automatisch. |
| close | Schließt nur von der Erweiterung erzeugte Tabs und mit closeWorkspace die eigenen Fenster; ein Fenster, das noch einen nicht von der Erweiterung geöffneten Tab enthält, bleibt unberührt. Die Erweiterung hat keine History-Berechtigung, also wird nichts aus dem Chrome-Verlauf entfernt. |

## Workspaces, Fenster und Inkognito

**Tabs eines Runs teilen sich ein Fenster, und eine Suche macht dieses Fenster inkognito**

Browser-Befehle eines Runs der Reihe nach und das Fenster, in dem jeder landet. Eine Suche legt das Fenster des Runs inkognito an, und ein späteres open schließt sich an. Ein click mit tabId erreicht diesen Tab, ein click ohne tabId und ohne browserWorkspaceId landet dagegen im aktuellen Fenster von Chrome. Ein open mit incognito: false startet ein Fenster im normalen Profil, das den Workspace des Runs übernimmt, und spätere Tabs folgen ihm.

- **Workspace** (browserWorkspaceId): open, search und extract mit URL legen neue Tabs im Fenster einer expliziten browserWorkspaceId an, sonst von run:<runId>, sonst von session:<sessionId>, außer der Aufruf verlangt das aktuelle Fenster oder den aktuellen Tab. Dieses Fenster wird unfokussiert mit 1280×900 erstellt.
- **Profil** (incognito): Nur search verlangt Inkognito, und open und extract schließen sich dem Fenster des Workspace an, egal in welchem Profil. Ein expliziter incognito-Wert, zu dem das Fenster nicht passt, öffnet ein neues Fenster, das den Workspace übernimmt, und Inkognito verlangt „Allow in Incognito“ für die Erweiterung.
- **Seitenaktionen** (tabId): click, type, press, select, check, upload, scroll, wait, inspect, screenshot und extract ohne URL nutzen tabId, sonst den aktiven Tab einer expliziten browserWorkspaceId, sonst den aktiven Tab im aktuellen Fenster von Chrome. Run- und Session-IDs steuern sie nicht.

Die Recherche läuft in einem eigenen, unfokussierten Chrome-Fenster von 1280×900 pro Browser-Workspace-ID, damit parallele Recherchestränge isoliert bleiben. Die ID kommt aus einer expliziten browserWorkspaceId, sonst aus dem Run, sonst aus der Session, sonst aus dem Befehl. Nur search verlangt Inkognito, was eine Suchserie aus Ihrem Verlauf heraushält und verlangt, dass die Erweiterung in Inkognito-Fenstern erlaubt ist. open und extract verlangen kein Profil und schließen sich dem bestehenden Fenster des Workspace an, nach einer Suche laufen sie also ebenfalls inkognito. Für angemeldete Arbeit übergeben Sie incognito: false. Ist das Workspace-Fenster inkognito, öffnet das ein Fenster im normalen Profil, das den Workspace übernimmt. Seitenaktionen ignorieren Run und Session. Sie nutzen tabId, dann eine explizite browserWorkspaceId und sonst das aktuelle Fenster von Chrome. Ohne explizite Wartebedingung lässt ein Bereitschafts-Timeout die Extraktion nicht scheitern. Sie liefert dann den aktuellen Inhalt mit einer Warnung.

> **Browser-Aktionen haben echte Auswirkungen** Der Agent kann in Ihrem Browser Formulare absenden und Dateien hochladen. Die Erweiterung hat keinen Zugriff auf die Cookie-API und ist angewiesen, keine Passwörter oder Zahlungsfelder abzufragen, aber ein Screenshot erfasst, was sichtbar ist, und der Desktop prüft jeden Upload-Pfad, bevor Chrome ihn sieht.