Letterbox

📌 Für den internen Produktionseinsatz gebaut. Die Architektur wurde über Monate täglicher KI-Entwicklung erprobt. Als Referenzimplementierung Open-Source veröffentlicht.

In einfachen Worten: Wenn du KI-Coding-Assistenten im Terminal nutzt, arbeitest du normalerweise mit einem zur Zeit – und zwei davon zur Zusammenarbeit zu bringen bedeutet, Nachrichten selbst zwischen Fenstern zu kopieren und einzufügen. Letterbox lässt zwei Assistenten (z. B. Claude und Gemini, oder Gemini und Mistral's Vibe) direkt miteinander sprechen und gemeinsam an einer Aufgabe arbeiten – freihändig.

Das Ergebnis: Ein Agent kann planen, während ein anderer überprüft, oder die beiden teilen sich die Arbeit – sie kollaborieren von selbst, während du zusiehst, statt jede Nachricht von Hand weiterzuleiten.

Ein kleines dateibasiertes Kommunikationsprotokoll, das es zwei KI-Agenten in getrennten Terminals ermöglicht, in Echtzeit miteinander zu sprechen.

Letterbox lässt zwei Terminal-Coding-Agenten – Claude Code, Gemini CLI, Antigravity oder Mistral's Vibe – ein Echtzeit-Gespräch führen, indem sie Nachrichtendateien über ein gemeinsames Verzeichnis austauschen. Wenn ein Agent spricht, wird eine 📬-Benachrichtigung in das Terminal des anderen eingespielt und weckt ihn zum Lesen und Antworten. Kein Netzwerk, kein Server, kein gemeinsamer Speicher: nur JSON-Dateien in einem Ordner und das atomare Umbenennen des Betriebssystems. Es ist die Messaging-Schicht, die für eine interne Planungsschleife gebaut wurde, 2026 als eigenständiges, versioniertes Tool extrahiert. Wenn du schon immer wolltest, dass zwei CLI-Agenten ohne Kopieren-und-Einfügen zwischen Fenstern an einer Aufgabe zusammenarbeiten, ist das genau richtig. Es bekommt gelegentlich Updates nach Belieben des Autors (der Launcher sagt dir, wenn eine neuere Version verfügbar ist) – aber es ist nicht unterstützt: keine Roadmap, keine Feature-Anfragen, kein Community-Projekt.

Die Brücke ist wirklich harness-übergreifend: Claude auf der einen Seite, Gemini auf der anderen, die über denselben Kanal sprechen, wurde live verifiziert. Der einzige Haken ist die Einrichtung – Claude verdrahtet sich automatisch, während Gemini und Antigravity Letterbox aus ihren eigenen Einstellungen laden. Der Abschnitt Setup pro Harness führt durch beides.

Warum es existiert

Ich arbeite jeden Tag mit zwei KI-Kollaborateuren – Claude und Gemini –, die jeweils in ihrem Terminal-Harness leben (Claude Code, Gemini CLI, Antigravity CLI und jetzt Mistral's Vibe). Letterbox ist, wie ich sie dazu bringe, miteinander zu sprechen, statt durch mich.

Das passiert in zwei Modi. Manchmal ist es manuell: Wir brainstormen und ich möchte das andere Modell in das Gespräch einbeziehen. Manchmal ist es automatisiert – in der Planungsschleife entwirft Claude einen Plan, und jeder Plan wird als eingebaute Stufe an Gemini zur Überprüfung weitergeleitet. Letterbox trägt beides auf dieselbe Weise.

Es ist bewusst harness-agnostisch – Claude Code ↔ Gemini CLI ↔ Antigravity CLI ↔ Vibe in jeder Kombination – und Paare desselben Modells funktionieren genauso gut: zwei Claude-Tabs oder zwei Gemini-Tabs, die über einen Kanal sprechen.

Related MCP server: claude-intercom

Was es ist

Jeder letterbox <harness>-Start führt zwei koordinierte Prozesse in einem Terminal aus:

  letterbox claude --channel demo --as alice
        │
        ├─ PTY-Parent  (the foreground letterbox process)
        │    • spawns the harness CLI as a PTY child
        │    • watches the channel directory for peer writes
        │    • injects 📬 notifications into the PTY on arrival
        │
        └─ the harness spawns:
             └─ letterbox mcp  (stdio MCP server, agent-spawned)
                  • send_message / check_messages / acknowledge
                  • check_latest_message / channel_info / list_channels

  Both sides coordinate ONLY through the filesystem:

        ~/.letterbox/channels/demo/
          msg-*.json           ← one file per message
          .read/alice.json     ← per-agent read markers
          .read/bob.json

Es gibt keinen Daemon, kein IPC, keinen Hintergrunddienst. Das Dateisystem ist das Koordinationsmedium – der PTY-Parent-Watcher sieht eine neue msg-*.json erscheinen und rendert eine Benachrichtigung; das Kanalverzeichnis ist dauerhaft, überprüfbar und cat-bar. Die Absturzwiederherstellung ist trivial, weil nichts Wertvolles im Speicher lebt.

Wie der Agent die Letterbox-Tools bekommt, unterscheidet sich pro Harness, und das ist das Einzige, was du einmal konfigurierst:

• Claude Code nimmt ein Start-Flag, also verdrahtet Letterbox es automatisch – es generiert eine temporäre MCP-Konfiguration und übergibt --mcp-config an claude. Nichts für dich einzurichten.

• Gemini CLI und Antigravity nehmen dieses Flag nicht; sie laden MCP-Server aus ihrer eigenen Einstellungsdatei. Du fügst dort einmal einen einzeiligen, kanalagnostischen letterbox-Eintrag hinzu, und der Launcher übergibt jeder Sitzung ihren Kanal und ihre Identität über Umgebungsvariablen beim Start – du musst also nie Einstellungen pro Kanal bearbeiten.

• Vibe lädt MCP-Server aus ~/.vibe/config.toml. Sein MCP-Subprozess erbt nur eine reduzierte Umgebung, daher ist ein einmaliges Brücken-Skript nötig, um LETTERBOX_CHANNEL / LETTERBOX_SENDER aus Vibes eigenem Prozess-Env weiterzuleiten. Sobald das eingerichtet ist, funktioniert jeder Kanal genau wie bei Gemini. Siehe den Abschnitt Vibe-Setup.

Für wen es ist

• Leute, die Terminal-Coding-Agenten nutzen und autonomen KI↔KI-Dialog auf einem Rechner wollen, ohne das Kopieren-Einfügen zwischen Fenstern zu beaufsichtigen.

• Leute, die Dateien als Quelle der Wahrheit schätzen – überprüfbar, durchsuchbar, kein undurchsichtiges Protokoll, keine Magie.

Für wen es NICHT ist

• Alle, die einen gehosteten oder vernetzten Chat-Dienst wollen – das Nachrichtenprotokoll ist dateisystemlokal und berührt nie das Netzwerk. (Der Launcher macht beim Start eine optionale, best-effort Versionsprüfung; deaktiviere sie mit LETTERBOX_NO_UPDATE_CHECK=1.)

• Alle, die eine Multi-User-Plattform wollen – es ist eine Punkt-zu-Punkt-Brücke zwischen Agenten auf einem Rechner, kein Hub für viele Benutzer (siehe Für zwei gebaut).

• Windows-native Benutzer – v1 ist nur POSIX (siehe Was wir nicht unterstützen).

• Alle, die ein unterstütztes Produkt wollen – Letterbox ist versioniert und bekommt gelegentlich Updates nach Belieben des Autors (der Launcher sagt dir, wenn eine neuere Version verfügbar ist), aber es gibt keine Roadmap, kein SLA und keine Verpflichtung, Feature-Anfragen anzunehmen oder die Wartung fortzusetzen. Nutze es so, wie es ist; zieh dir eine neuere Version, wenn sie hilft.

Für zwei gebaut

Letterbox ist im Kern eine Zwei-Wege-Brücke – ein Peer, der mit einem Peer spricht, ist das, wofür es entworfen und optimiert ist. Drei oder mehr Agenten können einen Kanal teilen: gezielte Adressierung (send_message(to="<label>")) und die participants-Liste machen es nutzbar, und Broadcasts im selben Kanal erreichen alle. Aber ein gemeinsamer Kanal ist ein Broadcast-Bus – jede Nachricht weckt jeden Teilnehmer. Ohne Orchestrierung (Reihenfolge, ein designierter Koordinator oder Regeln, wer wann spricht) wird ein N-Wege-Raum zu einem Benachrichtigungssturm, der die Nachrichten-/Nutzungslimits eines Modells überraschend schnell auffressen kann. Wenn du drei oder mehr willst, bring deinen eigenen Dirigenten mit. Das Substrat ist ehrlich darüber, wer im Raum ist; die Etikette liegt bei dir.

Installation

Letterbox wird aus dem Quellcode installiert (ein Wheel ist baubar; es ist derzeit nicht auf PyPI veröffentlicht). Aus dem Repository-Root:

pip install -e .          # or: pip install -e ".[dev]" for the test extras

Das setzt den Befehl letterbox auf deinen PATH. Der Befehl muss über den Namen auflösbar sein – jeder Agent startet letterbox mcp selbst – das ist also tragend. Bestätige es:

which letterbox           # note this absolute path; Gemini/Antigravity setup needs it

Du brauchst auch den Harness, den du startest (claude, gemini, antigravity oder vibe), installiert, auf deinem PATH und angemeldet. Letterbox startet ihn für dich.

Aktualisieren

Letterbox ist versioniert (letterbox.__version__, die einzige Quelle der Wahrheit); da es keine PyPI-Veröffentlichung gibt, ist der main-HEAD von git die Veröffentlichung. Bei einem benutzerorientierten Start macht die CLI eine best-effort Prüfung (höchstens einmal am Tag, zwischengespeichert unter ~/.cache/letterbox/) und gibt einen einzeiligen Hinweis aus, wenn eine neuere Version existiert. Zum Aktualisieren:

pip install --upgrade "git+https://github.com/dovahkiin-v/letterbox"

Das ist der einzige Netzwerkaufruf, den Letterbox jemals macht – das Nachrichtenprotokoll bleibt vollständig lokal. Er läuft mit einem knappen Timeout und ist vollständig fail-silent: Wenn er GitHub nicht erreichen kann, gibt er einfach nichts aus und verzögert deinen Start nie. Er wird nie für letterbox mcp (den Stdio-Server des Agenten) ausgeführt. Deaktiviere ihn vollständig mit LETTERBOX_NO_UPDATE_CHECK=1.

Setup pro Harness

Das machst du nur einmal pro Harness. Überspringe die Harnesses, die du nicht nutzt.

Claude Code – nichts zu tun

Letterbox verdrahtet Claude automatisch: Beim Start schreibt es eine temporäre MCP-Konfiguration (Modus 0600) und übergibt --mcp-config <Pfad> an claude. Die Letterbox-Tools erscheinen in dieser Sitzung und sonst nirgends. Es gibt keine Einstellungsdatei zu bearbeiten.

Gemini CLI – zwei einmalige Schritte

1. MCP-Server registrieren in ~/.gemini/settings.json (Datei erstellen, falls sie nicht existiert). Verwende den absoluten Pfad zu deinem installierten letterbox (von which letterbox oben) und übergib nur ["mcp"] – keinen Kanal, keine Identität:

{
  "mcpServers": {
    "letterbox": {
      "command": "/absolute/path/to/letterbox",
      "args": ["mcp"]
    }
  }
}

Dieser Eintrag ist absichtlich kanalagnostisch. Der Launcher exportiert LETTERBOX_CHANNEL, LETTERBOX_SENDER und LETTERBOX_INSTANCE_ID beim Start in Geminis Umgebung, und der MCP-Server liest sie – so dient derselbe einzelne Eintrag jedem Kanal, und du bearbeitest ihn nie wieder. (Das spiegelt, wie die Forge-Orchestratoren einen Kanal über eine Umgebungsvariable übergeben.)

2. Vertraue dem Ordner, aus dem du startest. Gemini weigert sich, in einem nicht vertrauenswürdigen Verzeichnis zu laufen, ohne eine interaktive „Vertraust du diesem Ordner?"-Abfrage – und eine blockierende TUI-Abfrage würde die Automatisierung aufhalten. Vertraue dem Startverzeichnis (oder einem übergeordneten) vorab in ~/.gemini/trustedFolders.json:

{
  "/home/you/projects": "TRUST_PARENT"
}

TRUST_FOLDER vertraut genau diesem Verzeichnis; TRUST_PARENT vertraut ihm und allem darunter, sodass ein Eintrag alle deine Projektordner abdeckt. (Tipp: Greif nicht zu Geminis --skip-trust-Flag, um das zu umgehen – es erzwingt eine Workspace-System-Prompt-Suche, die sogar in bereits vertrauenswürdigen Verzeichnissen abstürzt. Vertraue stattdessen dem Ordner.)

Antigravity (agy)

Starte es als letterbox agy … (die lange Form letterbox antigravity … funktioniert auch – agy ist nur ein Alias, der dem Binärnamen entspricht). Antigravity erhält seinen pro-Start-Kanal und seine Identität über dieselben Umgebungsvariablen wie Gemini; was sich unterscheidet, ist, wie du den MCP-Server registrierst. agy lädt MCP-Server aus Plugins, also installierst du Letterbox als winziges lokales Plugin (ein Verzeichnis mit zwei JSON-Dateien):

# 1. Build the plugin (one directory, two files). Use the absolute
#    `letterbox` path from `which letterbox`.
mkdir -p ~/.letterbox/agy-plugin/letterbox
cat > ~/.letterbox/agy-plugin/letterbox/plugin.json <<'JSON'
{ "name": "letterbox", "version": "1.0.0",
  "description": "Letterbox file-based AI-to-AI comms bridge." }
JSON
cat > ~/.letterbox/agy-plugin/letterbox/mcp_config.json <<'JSON'
{ "mcpServers": { "letterbox": {
    "command": "/absolute/path/to/letterbox", "args": ["mcp"] } } }
JSON

# 2. Install it (and confirm).
agy plugin install ~/.letterbox/agy-plugin/letterbox
agy plugin list

Die mcp_config.json ist aus demselben Grund kanalagnostisch wie Geminis Einstellungseintrag – der Launcher übergibt Kanal und Identität per Umgebung beim Start. Wie Gemini prüft auch agy die Ordnervertrauenswürdigkeit: Es respektiert eine trustedWorkspaces-Liste in ~/.gemini/antigravity-cli/settings.json, also füge das Verzeichnis, aus dem du startest, dort hinzu, falls es nicht schon vorhanden ist.

Status: die PTY-Schicht (Benachrichtigungen + Nachrichtenzustellung, beide Richtungen) ist live verifiziert, und das Plugin-Install oben verdrahtet die Tools sauber. Der vollständige Tools-in-agy-Roundtrip funktioniert frisch und ist leicht erprobt – behandle Antigravity als das neueste der drei und melde alles Ungewöhnliche.

Vibe (Mistral)

Starte es als letterbox vibe …. Vibe lädt MCP-Server aus ~/.vibe/config.toml, aber sein MCP-Subprozess erbt nur eine reduzierte Umgebung (HOME, PATH, SHELL, TERM, USER, LOGNAME) – also erreichen LETTERBOX_CHANNEL usw. es nicht über normale Vererbung. Ein kleines einmaliges Brücken-Skript behebt das, indem es sie beim Spawn über /proc aus Vibes Prozess liest. Danach funktioniert jeder Kanal genau wie bei Gemini – keine Konfigurationsbearbeitung pro Kanal.

1. Brücken-Skript installieren (wird mit Letterbox geliefert):

cp "$(python3 -c 'import letterbox.data, pathlib; print(pathlib.Path(letterbox.data.__file__).parent / "vibe-mcp-bridge.sh")')" \
   ~/.letterbox/vibe-mcp-bridge.sh
chmod +x ~/.letterbox/vibe-mcp-bridge.sh

2. Registriere es in ~/.vibe/config.toml. Ersetze jeden vorhandenen letterbox-Eintrag durch:

[[mcp_servers]]
name = "letterbox"
transport = "stdio"
command = "/home/YOU/.letterbox/vibe-mcp-bridge.sh"
args = []

Verwende deinen tatsächlichen Home-Pfad (nicht ~ – Vibe expandiert ihn möglicherweise nicht). Der Eintrag ist absichtlich kanalagnostisch: Das Brücken-Skript liest Kanal und Identität zur Laufzeit aus Vibes Prozess-Env, genau wie Gemini sie aus seiner Umgebung liest.

3. Fertig. Jeder Kanal funktioniert:

letterbox vibe --channel blueberry-fields --as mistral

Vibe startet auch mit --yolo (Auto-Approval), sodass eingespielte Benachrichtigungen es wecken können, ohne bei einer Tool-Abfrage zu blockieren.

Hinweis: Das Brücken-Skript verwendet /proc/$PPID/environ, um Vibes Umgebung zu lesen – nur Linux, was mit Letterbox' POSIX-only-Haltung übereinstimmt. macOS-Unterstützung würde einen anderen Mechanismus erfordern (ps -p $PPID -Ewww); derzeit nicht ausgeliefert.

Status: 📬 Wake-Injection ist nachweislich funktionsfähig (SCHRITT 0 hat verifiziert, dass Vibe's ChatTextArea Enter überschreibt, um zu senden, also gilt der Standard-PTY-Inject-Pfad). Behandle Vibe als das neueste der vier und melde alles Ungewöhnliche.

Schnellstart

Öffne zwei Terminals und richte jedes auf denselben Kanal mit einer eindeutigen Identität aus. Ohne Konfigurationsdatei liefern letterbox's eingebaute Standardwerte das gemeinsame globale Zustandsverzeichnis (~/.letterbox).

Eine echte Cross-Harness-Brücke — Claude spricht mit Gemini (schließe zuerst die Gemini-Einrichtung ab):

# Terminal 1
letterbox claude --channel demo --as claude

# Terminal 2
letterbox gemini --channel demo --as gemini

Oder zwei desselben Harness, falls du es einfach halten möchtest:

# Terminal 1
letterbox claude --channel demo --as alice

# Terminal 2
letterbox claude --channel demo --as bob

Beide Sitzungen starten und verharren ruhig. Nun stups den Agenten in Terminal 1 an — zum Beispiel „Sende eine Nachricht an deinen Peer." Von dort an weckt jede 📬-Benachrichtigung den anderen Agenten zum Lesen und Antworten: Diese Übergabe ist der ganze Sinn. Die --as <label>-Namen machen das Transkript lesbar; darunter verwendet die Nachrichtenfilterung eine Pro-Launch-Instanz-ID, nicht das Label.

Ein paar ehrliche Anmerkungen:

• Du führst letterbox mcp nie selbst aus. Dieser Unterbefehl ist der stdio-MCP-Server, der vom Harness gestartet wird — er ist für den Agenten, nicht für dich. Von Hand in einem Terminal ausgeführt, sagt er dir das und beendet sich.

• Launch-Argumente sind von Natur aus autonom. Der Claude-Adapter startet mit --dangerously-skip-permissions und der Gemini-Adapter mit --yolo, weil injizierte Nachrichten einen Agenten nicht aufwecken können, der durch einen Pro-Aktion-Genehmigungsdialog blockiert ist. Wenn das kein Kompromiss ist, den du eingehen willst, ist letterbox nicht die richtige Wahl — überschreibe die Argumente in letterbox.toml oder tritt zurück.

Für einen vollständigen, kommentierten Durchlauf (zwei Claudes, die darüber debattieren, ob ein Hot Dog ein Sandwich ist), siehe das Beispielprojekt unter examples/two-claudes-debating/.

Den Brückenzustand kennen

Da ein settings-verdrahteter Harness letterbox bei jeder Sitzung lädt, kann ein Agent die letterbox-Tools ohne aktive Brücke verfügbar haben — zum Beispiel eine einfache Gemini-Sitzung, die du nie über letterbox gestartet hast. Letterbox geht damit gelassen um und gibt dem Agenten eine Möglichkeit, dies zu prüfen:

• Eine einfache Sitzung ist ruhend, nicht defekt. Ohne Kanal verbindet sich der MCP-Server trotzdem (der Harness zeigt ein ruhiges „verbunden"), aber die Messaging-Tools bleiben still — sie schlagen nur mit einer klaren, handlungsfähigen Meldung fehl, wenn sie tatsächlich aufgerufen werden, und niemals von selbst. Eine bewusste einfache Sitzung wird nie zugemüllt; eine wirklich falsch konfigurierte Brücke zeigt sich in dem Moment, in dem der Agent zu sprechen versucht.

• channel_info ist das Brücken-Orakel des Agenten. Der Aufruf beantwortet serverseitig: Ist überhaupt eine Brücke aktiv? Auf welchem Kanal, als wer? Wer ist der Peer (beobachtet an seiner letzten Nachricht), wie viele ungelesene Nachrichten gibt es, und wann hat er zuletzt gesprochen? Ein Agent, der sich über seine Lage unsicher ist, kann fragen, bevor er sendet — „Peer hat vor 90 s gesprochen" liest sich ganz anders als „nie."

Kanäle beobachten und auflisten

Von jedem Terminal aus kannst du das rohe Gespräch beobachten oder sehen, welche Kanäle existieren:

letterbox tail --channel demo --follow   # stream messages as JSON, one per line
letterbox list-channels                  # list channels with last-activity

Um eine startende letterbox.toml zu erstellen, statt auf Standardwerte zu setzen:

letterbox init --channel demo            # writes ./letterbox.toml (project-local)
letterbox init --global                  # writes ~/.letterbox/config.toml instead

Betrieb

• Lesen holt dich auf den Stand; der Posteingang leert sich von selbst. check_messages gibt ungelesene Peer-Nachrichten zurück und rückt dabei den Lesemarkierungen des Agenten vor — aufeinanderfolgende Aufrufe blättern also durch den Rückstand, und ein geleerter Posteingang bleibt geleert, ohne manuelle Buchführung. check_latest_message ist ein nicht-vorrückender Blick für das übliche „Was hat er gerade gesagt?", und acknowledge dient der expliziten Einzelnachrichten-Steuerung.

• Ein Neustart ist ein frischer Anfang, keine Wiederholung. Beim Start wird die Lesemarkierung eines Agenten auf die neueste bereits auf der Platte befindliche Nachricht ausgerichtet, sodass er nur das sieht, was nach seinem Beitritt ankommt — er wird nicht mit der gesamten Kanalhistorie einer früheren Sitzung überflutet. Die Historie ist weiterhin vorhanden und auf Abruf erreichbar (check_messages mit einem since_id-Cursor); sie wird dir nur nicht aufgezwungen.

• Aufbewahrung ist manuell. Nachrichten leben im Kanalverzeichnis, bis du sie beschneidest; es gibt keine automatische Löschung (überraschendes Löschen ist in Kommunikationsinfrastruktur inakzeptabel). Pro-Agent .read/-Markierungen verfolgen den Lesestatus — sie rücken Markierungen vor, fassen die Dateien nie an und beeinflussen nie die Sicht des Peers.

• Praktische Obergrenze: ~10.000 unbeschnittene Nachrichten pro Kanal. Darüber hinaus können check_messages und list-channels spürbare Latenz zeigen. Beschneide oberhalb dieses Punktes.

• letterbox prune ist der sichere Weg, Speicherplatz zurückzugewinnen. Es ist standardmäßig ein Trockenlauf — es druckt, was passieren würde, und fasst nichts an. --yes-i-am-sure verschiebt passende Dateien in ein reversibles cold/-Unterverzeichnis; --delete --yes-i-am-sure (doppelt abgesichert) löscht endgültig. Dies ist der einzige destruktive Befehl in letterbox.

letterbox prune --channel demo --keep-last 100                   # preview (dry run)
letterbox prune --channel demo --keep-last 100 --yes-i-am-sure   # move to cold/
letterbox prune --help                                           # all selection rules

Ein Kanal ist nur ein Ordner, also funktioniert auch rm -rf ~/.letterbox/channels/demo — letterbox sperrt nichts.

Sicherheitsmodell

Das vollständige Bedrohungsmodell steht in docs/PROTOCOL.md. Kurz zusammengefasst:

• Der Peer-Agent auf einem Kanal ist nicht vertrauenswürdig. Seine Nachrichtentexte können Prompt-Injection-Payloads, ANSI-Escape-Sequenzen oder Shell-Metazeichen tragen. Letterbox behandelt beide Seiten als nicht vertrauenswürdig.

• Benachrichtigungen rendern nur aus vertrautem Kontext. Die 📬-Benachrichtigungsvorlage ersetzt Variablen, die aus der eigenen Konfiguration und den Beobachtungen des Watchers stammen ({channel}, {sender}, {message_id}, {timestamp}) — niemals aus dem Nachrichten-Payload des Peers. Ein bösartiger Peer kann alles in seine Datei schreiben; nichts davon gelangt in die injizierte Benachrichtigung. Nachrichtentexte werden nur sichtbar, wenn der Agent explizit check_messages aufruft. Dasselbe gilt für die Peer-Felder von channel_info: Sie werden aus dem Verkehr beobachtet und sind informativ, werden nie in eine Benachrichtigung eingespeist.

• Kein Ausführungspfad. Letterbox führt niemals exec, eval oder Shell auf einem Nachrichtentext oder Metadatenfeld aus. Unterprozesse werden mit argv-Listen erzeugt (niemals shell=True), und nur um den in letterbox.toml konfigurierten Harness zu starten.

• Pfadsicherheit. Kanalnamen und Nachrichten-IDs werden vor jeder Dateisystemoperation gegen ein strenges Muster validiert — ../etc oder alles mit einem Schrägstrich wird abgelehnt.

• Dateisystemberechtigungen. ~/.letterbox/ und Kanalverzeichnisse werden mit 0700 (nur Benutzer) erstellt; die generierte MCP-Konfiguration mit 0600.

Wogegen letterbox NICHT schützt: ein kompromittiertes lokales Benutzerkonto (Dateisystemberechtigungen sind die einzige Barriere), die eigenen Prompt-Injection-Schwachstellen des konsumierenden Harness oder Vertrauensgrenzen, die durch maschinenübergreifende Synchronisierung (NFS, syncthing) eingeführt werden. Es ist keine Verschlüsselung-at-Rest- oder Netzwerkvertrauensschicht — diese liegen bewusst außerhalb des Rahmens.

Umfang und Anti-Umfang

Was letterbox bewusst nicht tut, ist der Punkt, keine Lücke:

• Keine LLM-Aufrufe. Letterbox ruft nie ein Sprachmodell auf, gibt keinen Token aus und hält keinen API-Schlüssel. Die Benachrichtigungsvorlage ist gerenderter Text, kein Prompt.

• Keine Telemetrie, keine Metriken, keine Analytik. Es wird nichts gesammelt, keine Dashboards, keine Nutzungsverfolgung.

• Kein Phone-Home, kein Auto-Update, kein Versionscheck. Letterbox kontaktiert nie einen Server. Der erste Lauf ist still.

• Kein Netzwerk. Es ist dateisystemlokal. Maschinenübergreifende Nutzung ist die Sache deiner Dateisystem-Synchronisierung, nicht die von letterbox.

Dieser Anti-Umfang ist es, der letterbox klein, träge, prüfbar und dauerhaft macht.

Barrierefreiheit

• Standardmäßig Klartext (--format=plain) — pipe- und screenreader-freundlich; tail gibt Nachrichten-JSON auf stdout für jq aus. Strukturierte/farbige Ausgabe ist optional (--format=rich).

• Keine reine Farb-Signalisierung. --color=auto|always|never steuert Farbe unabhängig; Farbe ist nie der einzige Weg, einen Zustand zu vermitteln.

• stdout ist Daten, stderr ist Logs — Befehle pipen sauber.

• Durchgehend UTF-8. Die eigenen Zeichenketten des Tools sind Englisch; Nachrichtentexte sind in der Sprache, die du schreibst.

• Ruhige Oberfläche. Keine Spinner, keine Telemetrie-Banner, keine Upgrade-Belästigungen. Ruhiger Erfolg, klare Fehler — Fehler nennen den Pfad, die Zeile oder die gültigen Optionen.

Was wir nicht unterstützen

Letterbox v1 ist nur für POSIX (Linux und macOS). Die PTY-Spawn-und-Inject-Schicht basiert auf POSIX-Primitiven; Windows-Unterstützung über das stdlib-pty-Modul ist unvollständig und wird nicht ausgeliefert. Wenn du unter Windows arbeitest, wird letterbox in v1 für dich nicht laufen — besser, das jetzt zu wissen, als auf einen Absturz zu stoßen.

Siehe auch

• examples/two-claudes-debating/ — der praktische Durchlauf: zwei Claude-Code-Sitzungen, die in Echtzeit debattieren.

• skills/letterbox/SKILL.md — die agentenorientierte Nutzungs-Anleitung: wie ein LLM eine Live-Brücke nutzt (Broadcast, gerichtete Nachrichten, Teilnehmer).

• skills/letterbox-setup/SKILL.md — die agentenorientierte Einrichtungs-Anleitung: die einmalige MCP-Verdrahtung pro Harness, die Ein-Label-pro-Kanal-Regel und die Neustart-Prozedur nach einem Upgrade.

• docs/AGENT_POINTER.md — ein kurzer Drop-in-Block zum Einfügen in die CLAUDE.md / GEMINI.md / AGENTS.md eines Projekts, damit ein Agent weiß, dass er auf einer Brücke ist.

• Die vollständige Dateiformat- und Protokollreferenz steht in docs/PROTOCOL.md.

• DECISIONS.md — die Architektur-Entscheidungsprotokolle (ADRs) hinter jeder tragenden Entscheidung, einschließlich der MCP-Verdrahtung pro Harness (ADR-054/055), des Ruhemodus und des channel_info-Orakels (ADR-056), des Submit-Timing-Fixes (ADR-057), der selbstwartenden Lesemarkierung (ADR-058), der Duplikat-Instanz-Sperre pro Kanal (ADR-061), der N-Parteien-gerichteten Adressierung + Teilnehmer (ADR-062) und des Vibe-Adapters + Textual-Submit-Vertrags (ADR-067).

• LICENSE — MIT.

Status

Letterbox ist ein versioniertes, nicht unterstütztes Artefakt — MIT-lizenziert, unter github.com/dovahkiin-v/letterbox. Es wird vollständig ausgeliefert und steht wie dokumentiert; es ist ein persönliches Artefakt, kein Produkt, und wirbt nicht um Beiträge. Nicht unterstützt bedeutet keine Roadmap, kein SLA und kein Versprechen, Probleme zu beheben oder Feature-Anfragen anzunehmen — aber es ist nicht eingefroren: Der Autor kann nach eigenem Belieben eine spätere Version herausbringen, ohne Zeitplan. Der einmal tägliche Update-Check des Launchers sagt dir, wann das passiert (LETTERBOX_NO_UPDATE_CHECK=1 zum Stummschalten). Siehe CONTRIBUTING.md für das, was das in der Praxis bedeutet.