AgentBridge

Status: Mitte der Migration, und diese README beschreibt den älteren Stand.

AgentBridge begann als Brücke von Claude Code zu Codex/Antigravity, und alles, was unten dokumentiert ist, funktioniert heute. Es wird generalisiert, sodass jede unterstützte CLI der Orchestrator sein kann und jede andere ein Worker, mit Routing, das von einem Benutzerprofil gesteuert wird, statt von hartcodierten Modellnamen.

Wie es weitergeht, steht in docs/architecture.md und docs/roles.md. In Arbeit: eine Provider-Adapter-Schicht (src/providers/), ein Routing-Profil (src/profile/) und ein agentbridge init-Setup-Ablauf. Der Cursor-Adapter ist vorhanden, aber unverifiziert — seine Flags wurden aus bisherigem Wissen geschrieben, statt von einer installierten CLI abgelesen, und genau das steht oben in der Datei.

Bis die Migration abgeschlossen ist, behandle die Abschnitte unten als zutreffend für Codex- und Antigravity-Worker und die Doku als zutreffend für das Design.

Orchestratoren

AgentBridge stellt seine /agentbridge …-Befehlsschnittstelle als MCP-Prompts bereit, sodass jeder MCP-Client, der prompts/list unterstützt, dieselben Befehle direkt vom Server erhält — keine host-spezifischen Befehlsdateien, die installiert oder synchron gehalten werden müssten.

Die Doktrin hinter diesen Befehlen liegt in doctrine/ und nennt keine Modelle — sie routet nach Rolle, und .agentbridge/profile.json bildet Rollen auf das ab, was der Benutzer tatsächlich installiert hat.

Ein kleiner lokaler stdio-MCP-Server, der es Claude Code ermöglicht, Arbeit an die Codex-CLI und die Antigravity-CLI (agy) als externe Worker zu delegieren — unter Verwendung der CLI-Sitzungen, in denen du bereits angemeldet bist, ohne API-Keys.

Claude bleibt der Orchestrator. AgentBridge ist bewusst schlichte Verrohrung: Es verwandelt Claudes strukturierte Anfrage in einen Worker-Prompt, führt die CLI aus und gibt ein kompaktes, strukturiertes Ergebnis zurück.

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

Related MCP server: agent-intern

Was es nicht ist

Kein Cloud-Dienst, keine Web-UI, keine Datenbank, kein Daemon, kein Dashboard, keine Job-Warteschlange, kein Kontosystem und keine API-Key-Verwaltung. Es ist ein einziger Node-Prozess, den Claude Code über stdio startet und beim Beenden stoppt.

So funktioniert es

1. Claude ruft codex_run oder antigravity_run mit einer strukturierten Anfrage auf (goal, mode, model, effort, paths, contract, acceptance criteria…).

2. AgentBridge setzt aus genau diesen Feldern einen Worker-Prompt zusammen. Es führt kein eigenes Modell aus — das ist String-Zusammenbau, keine Inferenz.

3. Es reserviert Schreibbereiche, erstellt einen Snapshot des git-Arbeitsbaums und startet die CLI mit einem Argument-Array (shell: false).

4. Es parst die maschinenlesbare Ausgabe der CLI, extrahiert das endgültige Ergebnis des Workers (niemals dessen interne Überlegungen), erstellt einen Diff des git-Baums, um festzustellen, was sich tatsächlich geändert hat, und gibt ein kompaktes JSON-Ergebnis zurück.

Ein MCP-Aufruf = ein Worker-Versuch. AgentBridge wiederholt nie. Ob ein weiterer Versuch sinnvoll ist, entscheidet Claude.

Anforderungen

AgentBridge liest, kopiert, exportiert oder verändert niemals deine Codex- oder Antigravity-Anmeldedaten. Es ruft die CLIs genau so auf, wie es ein angemeldeter Mensch tun würde.

Installation und Build

npm install

npm run build

npm test

Die Testsuite verwendet durchgehend gemockte Prozesse, sodass ein normales npm test kein Modellkontingent verbraucht.

Bei Claude Code registrieren

Einmal auf Benutzerebene registrieren, damit jedes Projekt es verwenden kann:

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

Von einem Terminal aus verifizieren:

claude mcp list

claude mcp get agentbridge

Dann von innerhalb von Claude Code verifizieren, indem du /mcp ausführst. Du solltest agentbridge als verbunden aufgelistet sehen, mit drei Tools: codex_run, antigravity_run, bridge_status. Bitte Claude, bridge_status aufzurufen, um einen vollständigen Gesundheitsbericht zu erhalten.

Wenn du AgentBridge neu baust, starte Claude Code neu (oder verbinde den Server über /mcp neu), damit es das neue dist/ übernimmt.

Projektverzeichnis

Worker laufen in einem einzigen Projektverzeichnis und sind darauf beschränkt; es wird in dieser Reihenfolge aufgelöst:

1. AGENTBRIDGE_PROJECT_DIR, dann das bisherige CLAUDE_PROJECT_DIR (das Claude Code exportiert).

2. Das erste file://-Wurzelverzeichnis, das der MCP-Client bekannt gibt.

3. Das Arbeitsverzeichnis des Serverprozesses.

bridge_status berichtet, welches verwendet wurde.

Tools

codex_run

Modelle. Drei Slugs sind adressierbar, und jeder wird unverändert an die CLI übergeben:

Effort-Mapping (Orchestrator-Bezeichnung → Codex model_reasoning_effort):

Das Mapping ist vollständig und deterministisch. Die ultra-Stufe von Codex ist bewusst nicht bereitgestellt: Nur einige Modelle bieten sie an, und eine sechste Bezeichnung, die für zwei von drei Modellen funktioniert, würde das Routing modellabhängig machen.

Verfügbarkeit. Vor dem Start prüft AgentBridge das angeforderte Modell und den Effort gegen den eigenen Modellkatalog der Codex-CLI (models_cache.json in CODEX_HOME) — ein Dateizugriff, keine Inferenz.

• Modell gelistet, Effort gelistet → der Auftrag läuft

• Modell gelistet, Effort nicht → invalid_effort, mit details.supported_efforts

• Modell nicht gelistet → requested_model_unavailable, mit details.available_models

• kein lesbarer Katalog → der Auftrag läuft trotzdem, mit einer Warnung, dass die Verfügbarkeit unverified war

Es wird niemals etwas durch etwas anderes ersetzt. Eine Routing-Entscheidung, die nicht erfüllt werden kann, wird als strukturierter Fehler zurückgegeben, der genügend Metadaten für ein einstufiges Umrouting enthält, statt als stillschweigend schwächeres Modell.

Der aufgebaute Aufruf lautet:

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

wobei der Prompt über stdin gestreamt wird. Modell, Effort und Sandbox werden bei jedem Aufruf übergeben, sodass ein Lauf niemals das erbt, was gerade in ~/.codex/config.toml gesetzt ist.

analyze und review verwenden die echte read-only-Sandbox von Codex — Schreibzugriffe werden tatsächlich verhindert, nicht nur abgeraten.

antigravity_run

Gleiches Schema, mit:

Logische Namen werden zur Laufzeit gegen die aktuelle agy models-Liste aufgelöst:

Antigravity kodiert die Reasoning-Stufe in der Modell-ID, sodass model + effort zu einer einzigen ID aufgelöst werden und kein separates --effort-Flag gesendet wird — die beiden können nie widersprüchlich sein. Flash hat nur diese drei Stufen: extra high und max geben invalid_effort zurück, statt stillschweigend eine schwächere Stufe auszuführen, als du angefordert hast.

Antigravity ist absichtlich auf die günstige Gemini-Stufe beschränkt. Die Claude-Modelle, die agy ebenfalls anbietet, werden nicht als routbare Bezeichnungen bereitgestellt — für Reasoning auf Claude-Niveau verwende Claude Code selbst oder Codex, die echtes Sandboxing und (bei Codex) wählbaren Effort bieten.

Das Label hat eine geordnete Kandidatenliste von IDs für dasselbe Modell. Wenn keines davon von der installierten CLI angeboten wird, schlägt der Aufruf mit requested_model_unavailable und der vollständigen Liste verfügbarer Modelle fehl. Es fällt niemals stillschweigend auf ein anderes Modell zurück. Die aufgelöste ID wird bei jedem Lauf in warnings zurückgemeldet.

Der erzeugte Aufruf ist:

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commands wird nur für implement-Läufe hinzugefügt: Die CLI ignoriert --mode plan, wenn die Slash-Command-Erweiterung deaktiviert ist, sodass das Senden beider stillschweigend das einzige No-Write-Verhalten verwerfen würde, das Antigravity bietet.

bridge_status

Keine Argumente. Verbraucht keine Modellinferenz – es führt nur --version-Sonden, agy models, ein git rev-parse und eine Lektüre des Modell-Caches der Codex-CLI aus.

Gibt zurück:

• AgentBridge-Version, Projektverzeichnis (und wie es aufgelöst wurde), Node/Plattform

• git_verification – ob git-basierte files_changed / scope_violations hier überhaupt funktionieren. Wenn nicht, ist ein leeres scope_violations Stille, kein sauberes Gesundheitszeugnis, und die Warnungen sagen das

• codex.installed / version / path / auth

• codex.model_status – pro Modell: available | unavailable | unverified, die AgentBridge-Effort-Labels, die es akzeptiert, und die rohen Reasoning-Ebenen der CLI

• codex.model_source – woher die Verfügbarkeit stammt und wie frisch sie ist

• antigravity.installed / version / path / auth, erkannte Modelle, wie jedes logische Label + Tier aufgelöst wurde, und model_status in derselben Drei-Zustands-Form

• antigravity.unsupported_efforts – die Orchestrator-Labels, die Flash nicht übernehmen kann

• aktive Jobs und ihre Schreibbereiche

• Warnungen

Verfügbarkeit wird nie geraten. Wenn die installierte CLI keinen billigen Beweis bietet, ist der Status unverified statt einer Behauptung in die eine oder andere Richtung.

Es gibt niemals Anmeldedaten oder Umgebungsvariablen zurück.

Ergebnisformat

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effort ist für beide Anbieter vorhanden – die Codex-Reasoning-Ebene oder die Flash-Stufe, die die Modell-ID kodiert. files_changed und scope_violations werden von AgentBridge aus git berechnet, nicht vom Wort des Arbeiters übernommen. Internes Reasoning wird verworfen. summary ist auf 16 000 Zeichen begrenzt, wobei Kopf und Ende erhalten bleiben und summary_truncated: true gesetzt wird, wenn es abgeschnitten wird.

Fehler

Fehler geben dieselbe Hüllenform zurück mit status: "failed", einer error-Kategorie, einer umsetzbaren message und – wo verfügbar – exit_code, stderr_tail und einem details-Objekt.

Beispiele für Claude-Aufrufe der Worker

Günstige, schnelle Analyse:

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

Anspruchsvolle Implementierung, maximales Reasoning, eng begrenzt:

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

Zwei Codex-Worker mit disjunkten Bereichen – diese laufen parallel:

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

Antigravity für günstige mechanische Arbeit:

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

Nebenläufigkeit und Dateibereich

• implement erfordert allowed_paths. Pfade werden gegen das Projektverzeichnis normalisiert; alles, was es verlässt (.., andere Laufwerke, absolute Pfade anderswo), wird abgelehnt, bevor ein Prozess startet.

• Aktive implement-Jobs halten ihre Schreibbereiche im Speicher. Ein neuer Job, dessen Bereiche sich mit einem aktiven überschneiden, wird mit scope_conflict abgelehnt. Disjunkte Bereiche laufen parallel – unzusammenhängende Arbeit wird nie serialisiert.

• analyze und review reservieren nichts: Sie blockieren nie und werden nie blockiert.

V1-Einschränkung: Erkennung, nicht Isolierung

Dateibereichsschutz erkennt und meldet Verstöße; er sandkastet nicht jeden Worker in seinen eigenen Baum. Ein Codex-implement-Worker läuft mit workspace-write über das gesamte Projekt, sodass er kann außerhalb seiner allowed_paths schreiben – AgentBridge listet jede solche Datei in scope_violations auf, stuft den Status von success herab und sagt es dir deutlich.

Es wird nie automatisch etwas zurückgesetzt. Das Zurücksetzen einer Datei, die bereits vor dem Start des Workers geändert wurde, würde deine (oder Claudes) vorhandene Arbeit zerstören. Erkennung plus ehrliche Berichterstattung ist der V1-Vertrag; Git-Worktree-Isolierung ist bewusst nicht im Umfang enthalten.

Die Zuordnung ist vorsichtig mit dem vorherigen Zustand: Dateien, die vor einem Lauf bereits geändert waren und danach byte-identisch sind, werden dem Worker nie angelastet. Der Vergleich verwendet Porzellan-Status plus Inhalts-Hashing, und committete Dateien werden über einen HEAD-Verschiebungs-Diff erfasst.

Sicherheit

• Prozesse werden mit Argument-Arrays und shell: false erzeugt – niemals mit einer interpolierten Befehlszeichenkette. Shell-Metazeichen in Argumenten bleiben wörtlich.

• Windows-.cmd/.ps1-Launcher (die Node ohne Shell nicht starten kann) werden zu ihrem echten Node-Einstiegsskript aufgelöst und als node <script> ausgeführt, sodass shell: true nie benötigt wird.

• Prompts gehen über stdin an Codex; übergroße Antigravity-Prompts werden in eine temporäre Datei geschrieben und per Pfad referenziert. Keines kann das Windows-32-767-Zeichen-Kommandozeilenlimit erreichen.

• tests ist Kontext für den Worker. AgentBridge führt es nie aus, und es gibt kein MCP-Argument, das zu einem Befehl wird, den AgentBridge ausführt.

• Pfad-Traversal außerhalb des Projektverzeichnisses wird abgelehnt.

• Timeouts töten den gesamten Prozessbaum: taskkill /T /F unter Windows und unter POSIX ein SIGTERM an die Prozessgruppe, das nach einer 3-Sekunden-Gnadenfrist zu SIGKILL eskaliert. Die Eskalation überlebt bewusst den direkten Kindprozess, da genau dann Nachkommen noch laufen können. Dies ist Best-Effort – Node stellt kein Windows-Job-Objekt bereit. Wenn also taskkill selbst nicht starten kann, ist nur das direkte Kind erreichbar.

• Ausgabepuffer sind begrenzt (8 MB pro Stream) und UTF-8 wird erst nach dem Wiederzusammensetzen dekodiert, sodass Mehrbyte-Zeichen nie geteilt werden.

• Protokolle erfassen nur Job-Metadaten. Nie Tokens, nie die Umgebung, und Prompts/Ausgaben nur bei AGENTBRIDGE_DEBUG=1.

• Wovor AgentBridge dich nicht schützt: Der Worker ist ein echter Codierungsagent, der mit deinen Berechtigungen läuft. Im implement-Modus kann er über seine eigene Tooling Repository-Befehle ausführen. Lege deine allowed_paths entsprechend fest.

Verifizierung

AgentBridge führt nach dem Beenden eines Workers die eigenen Prüfungen des Projekts selbst aus, außerhalb jeder Sandbox, und gibt die echte Ausgabe in verification zurück:

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands – führen Sie genau diese aus, in jedem Modus.

• In implement-Modus weggelassen – AgentBridge liest package.json und führt die Skripte typecheck und test aus, falls sie existieren. Es führt build, dev oder start nie von sich aus aus; fragen Sie explizit danach.

• skip_verification: true – nichts ausführen und sich auf das Konto des Workers verlassen.

Befehle laufen ohne Shell, sodass |, &&, ;, > und Backticks außerhalb von Anführungszeichen abgelehnt statt halb ausgeführt werden. Ein fehlgeschlagener Check setzt error: "verification_failed" und stuft ein success auf partial herab, sodass ein Worker, der grüne Tests behauptet, die Tests selbst nicht übertrumpfen kann.

tests_or_checks_run und test_results berichten, was AgentBridge tatsächlich ausgeführt hat, wann immer eine Verifizierung stattfand; sie fallen nur dann auf die eigenen Behauptungen des Workers zurück, wenn dies nicht der Fall war.

Da die Befehle aus dem Repository stammen, kann ein Brief, der den falschen Runner nennt, AgentBridge nicht dazu bringen, ihn auszuführen: Ein Repository, dessen Testskript node --import tsx --test ist, wird damit geprüft, egal was der Brief sagte.

Umgebungsvariablen

AGENTBRIDGE_CODEX_SANDBOX=auto verwendet read-only für analyze/review und workspace-write für implement – außer dass ein sandboxierter Codex-Worker unter Windows die Ausgabe eines Unterprozesses nicht erfassen kann (spawn EPERM bei gepiptem stdio), was npm-Skripte, Testrunner und Bundler alle tun – er kann also lesen und bearbeiten, aber nie einen Testrunner, Typprüfer oder Build ausführen. Das ist eine Codex-Einschränkung ohne Konfigurationsknopf, daher fallen implement-Jobs auf danger-full-access zurück, sobald eine einmalige Sonde dies bestätigt, und sagen es in warnings. Analyze und review behalten ihre erzwungene read-only-Grenze. Unter Windows, wenn ein Lauf mit dem defekten Sandbox-Helfer fehlschlägt (helper_unknown_error: apply deny-read ACLs), versucht AgentBridge diesen Job einmal mit danger-full-access, merkt sich das Urteil für den Rest des Prozesses und fügt jedem betroffenen Ergebnis eine Warnung hinzu, dass die Grenze nicht durchgesetzt wurde. Nichts anderes löst diesen Fallback aus, und ein Neustart von AgentBridge versucht die echte Sandbox erneut – eine behobene Codex-Version stellt sie also automatisch wieder her. macOS und Linux sondieren, wiederholen oder fallen nie zurück.

Protokolle sind eine JSON-Zeile pro Job: Zeitstempel, Job-ID, Anbieter, Modell, Effort, Modus, Projekt, Dauer, Exit-Code, Fehlerkategorie.

Fehlerbehebung

executable_not_found – die CLI ist nicht im PATH, den Claude Code an untergeordnete Prozesse exportiert. Bestätigen Sie mit codex --version / agy --version in derselben Shell oder setzen Sie AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN.

authentication_required – Ihre CLI-Sitzung ist abgelaufen. Beheben Sie es in einem Terminal: codex login für Codex oder melden Sie sich erneut mit agy an. AgentBridge hat bewusst keine Möglichkeit, dies zu reparieren: Es berührt keine Anmeldedaten.

requested_model_unavailable — die Modelliste hat sich geändert, oder die installierte CLI hat dieses Modell nie angeboten. Führe bridge_status (oder agy models) aus, um zu sehen, was tatsächlich angeboten wird. Die Fehlerdetails enthalten diese Information bereits. AgentBridge schlägt hier absichtlich fehl, anstatt stillschweigend ein anderes Modell auszuführen. Wenn ein Anbieter eine Modell-ID umbenannt hat, füge die neue ID zu der entsprechenden Liste in src/models/antigravity.ts (bzw. CODEX_MODELS in src/models/codex.ts) hinzu und baue neu.

output_parse_failed — die CLI hat ihr maschinenlesbares Ausgabeformat geändert. Prüfe details.stdout_head im Ergebnis und vergleiche es mit parseCodexEvents / parseAgyOutput.

Nach einem CLI-Update — führe die Tests erneut aus, dann den Live-Check:

SMOKE_LIVE=1 node scripts/smoke.mjs

Dieser startet eine echte MCP-Sitzung und führt die günstigste Konfiguration jedes Workers aus. Ohne SMOKE_LIVE=1 wird nur der Handshake durchgeführt und bridge_status aufgerufen, was keine nennenswerten Kosten verursacht.

files_changed ist immer leer — das Projektverzeichnis liegt nicht in einem Git-Arbeitsbaum. Die Warnung im Ergebnis weist darauf hin. Für die Änderungsprüfung wird Git benötigt.

Unter /mcp erscheint nichts — prüfe, ob der registrierte Pfad auf dist/index.js zeigt (nicht auf src/), und starte Claude Code nach einem Neubuild neu.

Layout

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check