Relay Dokumentation

Installation

Relay ist derzeit über die Warteliste angekündigt. Die Download-Seite zeigt die aktuelle Verfügbarkeit; die folgenden Kapitel beschreiben den aktuellen Entwicklungsstand der App.

Erste Schritte

Nach der Installation bist du in drei Schritten startklar.

Tastenkürzel

Die wichtigsten Keyboard Shortcuts für schnelles Arbeiten.

Theme-System

Relays Theme-System besteht aus drei Ebenen, die zusammen das gesamte Erscheinungsbild der App steuern.

Drei-Ebenen-Architektur

Jedes Theme setzt sich aus drei unabhängigen Ebenen zusammen, die zusammenwirken.

Glass Themes

Moderne Themes mit Glassmorphism, Glow-Effekten und eigener Typografie — eine Auswahl:

Retro Themes

Neun historische Terminals (1973–1989) als vollständige visuelle Identitäten mit Scanlines und Perioden-Fonts.

Design-Tokens

Jedes Theme definiert 93 Design-Tokens, die das gesamte Erscheinungsbild steuern.

Hell/Dunkel-Modus

Relay unterstützt ein helles und ein dunkles Theme mit automatischem Wechsel basierend auf der macOS-Systemeinstellung.

Farb-Schema

Der Modus wird in den Einstellungen unter Erscheinungsbild → Farb-Schema konfiguriert. Bei System wird die macOS-Einstellung beobachtet und das Theme sofort gewechselt.

Pane-Layouts

Elf Layout-Presets teilen deinen Workspace in bis zu vier Panes. Workbench ergänzt zwei obere Arbeitsbereiche um ein Terminal-Dock; Workbench 2 teilt dieses Dock in zwei Terminals.

Prompt-Stile

10 Prompt-Stile im Relay-managed-Modus — Relay Compact, Robbyrussell, Minimal, Lambda, Powerblocks, Pure, Classic, Fish, Lean, Ops. Im User-zshrc-Modus läuft dein eigener Prompt (Powerlevel10k, Starship …) unverändert weiter.

Workspaces

Workspaces sind isolierte Arbeitsumgebungen mit eigenem State. Jeder Workspace speichert:

• Eigenes Theme und Terminal-Farbpalette
• Eigenes Pane-Layout (Single, 2×2, Focus, etc.)
• Eigene Panes mit individuellen Shells
• Persistenz zwischen Sessions (Tabs, CWD, Layout)
• Broadcast-Modus: Eingabe an mehrere Panes gleichzeitig
• Optionaler eigener Shell-Pfad pro Workspace

Project Memory

Relay speichert Kontext pro Projekt-Verzeichnis persistent auf Disk. Commands, Verzeichnisse und Nutzungshäufigkeit bleiben über Sessions hinweg erhalten.

• Commands werden pro Projekt dedupliziert gespeichert — mit Nutzungshäufigkeit und letztem Exit-Code
• Besuchte Verzeichnisse werden mit Besuchszähler und Zeitstempel erfasst
• Aufbewahrung konfigurierbar: 7 Tage, 30 Tage oder unbegrenzt
• Die häufigsten Commands erscheinen in der Sidebar unter 'Project History'

Speicherort

Pro Projekt wird eine JSON-Datei unter dem konfigurierten Pfad gespeichert (Standard: ~/.config/relay/memory/). Max. 500 Commands und 200 Verzeichnisse pro Projekt.

Beim App-Start werden alte Einträge basierend auf der Retention-Einstellung automatisch bereinigt. Leere Projektdateien werden entfernt.

Shell-Integration

Relay integriert sich tief in die Shell, um Befehle, Exit-Codes und Arbeitsverzeichnisse zu tracken. Die Integration wird bei jedem Start automatisch installiert.

Unterstützte Shells

OSC-Sequenzen

Relay nutzt Operating System Command (OSC) Sequenzen für die Kommunikation zwischen Shell und App.

Shell-Modi

Relay bietet zwei Modi für die Shell-Konfiguration.

Per-Pane Shell-Modus

Jeder Pane kann individuell zwischen Relay-Prompt und User-zshrc umgeschaltet werden — direkt im Pane-Header, ohne die Einstellungen zu öffnen.

• Ein Badge im Pane-Header zeigt den aktiven Modus: 'relay' (Terminal-Icon) oder 'zshrc' (Person-Icon)
• Ein Klick fragt vor dem Wechsel nach Bestätigung: Der Moduswechsel beendet die aktuelle Shell und startet sie neu.
• Jeder Pane behält seinen eigenen Modus — unabhängig von anderen Panes und der globalen Einstellung

Info-Panel

⌘I wechselt zwischen schmaler Leiste und geöffnetem Infopanel. Project bündelt Umgebung und Verlauf, Library wiederverwendbare Sammlungen, Global systemweite Werkzeuge und Agenten. AI öffnet den Workspace-Chat. Git lebt in der linken Git-Perspektive; Pipeline-Details im Workspace-Status.

Offene Ports

Relay erkennt automatisch offene Ports und die zugehörigen Prozesse auf dem System.

• Automatische Erkennung aller lauschenden TCP-Ports
• Anzeige von Port, Prozessname und PID
• Process-Tree-Kill per Klick (getpgid + SIGKILL)
• Sudo-Fallback bei fehlenden Rechten (kopiert Befehl in Clipboard)

VPN-Erkennung (geplant)

Geplant: Relay soll aktive VPN-Tunnel (OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cisco AnyConnect und weitere Provider) erkennen und Interface, IP und Provider im Info-Panel anzeigen. Noch nicht in der App enthalten.

AI Agent

Aktiviere AI unter Einstellungen → AI und richte eine API, einen lokalen Server oder eine installierte Agent-CLI ein. relay ask antwortet im Terminal; ⌘⌥A öffnet das separate AI-Chatfenster mit dem Kontext des aktiven Workspaces.

Verwendung

In zsh/bash bleibt relay ask auch bei einer CLI-Verbindung in der Relay-Oberfläche. relay agent öffnet ausdrücklich die Originaloberfläche der konfigurierten CLI. relay status zeigt die aktive Verbindung, relay resume die Relay-Sitzungsauswahl.

Mit -f hängst du eine Datei an (mehrfach möglich), -k setzt das letzte Relay-Gespräch fort, -m wählt ein Modell und -q reduziert die Formatierung. Fragen, die mit einem Bindestrich beginnen, folgen nach --.

Verbindungen und Modelle

Unterstützt werden OpenAI, Anthropic, Google Gemini und lokale OpenAI-kompatible Server. Wähle das Modell in den Einstellungen aus der für deine Verbindung verfügbaren Liste. Für den CLI-Modus muss die gewählte CLI installiert und angemeldet sein.

MCP-Bridge — Relay von aussen steuern

Relay öffnet auf Wunsch einen lokalen MCP-Server (Einstellungen → Intelligence), über den externe CLI-Agents wie Claude Code oder Codex CLI die Agent-Tools nutzen: Workspaces anlegen, Panes teilen, Layouts und Themes wechseln, To-dos und Notizen verwalten. Der Socket ist ein lokaler Unix-Socket (0600), der Python-Shim wird automatisch installiert.

Shell-Aktionen (run_command, write_file, git_push, write_to_terminal) verlangen IMMER eine Bestätigung pro Aufruf in Relay — mit 120-Sekunden-Timeout. Datei-Lese- und Clipboard-Tools sind über MCP grundsätzlich nicht erreichbar.

DevTools im Browser-Pane

Jeder Browser-Tab kann ein DevTools-Pane anhängen — mit acht Tabs:

Console mit Eval, Live-Autocomplete und $0/$1/$_; Network mit Request-Bodies, Typ-Filtern, Waterfall, Throttle, HAR-Export und Replay (Copy as fetch/cURL); Elements mit Live-DOM-Baum, zuschaltbaren CSS-Regeln und editierbaren Attributen. ⌥⌘I öffnet zusätzlich Safaris eigenen Web Inspector.

SSH & SFTP

Relay liest ~/.ssh/config (inklusive ProxyJump), zeigt gespeicherte Hosts mit Live-Latenz (alle 15 Sekunden) in der Sidebar und verwaltet Tunnel. Bricht eine Verbindung ab, erscheint ein Reconnect-Banner statt einer toten Session.

Der SFTP-Browser zeigt lokale und entfernte Dateien nebeneinander: durchsuchen, umbenennen, löschen sowie hoch- und herunterladen. Der separate Editor-Modus lädt das Remote-Verzeichnis bei Bedarf in einen lokalen Cache und überträgt Änderungen zurück.

Automatisches Error-Explain

Wenn ein Befehl mit einem Fehler-Exit-Code endet, bietet Relay an, den Fehler automatisch vom AI-Agenten erklären zu lassen.

• Fehlgeschlagene Commands werden in der Sidebar mit einem roten Punkt und einem 'Explain?'-Badge markiert
• Ein Klick öffnet die integrierte Erklärung am Befehl. Im Terminal kannst du alternativ relay explain verwenden.
• Erfordert eine konfigurierte AI-Verbindung in den Einstellungen.

Semantic Colorizer

Relay coloriert Terminal-Ausgaben automatisch: Fehler, Warnungen, URLs, Pfade und Zahlen erhalten kontextbezogene Farben — ohne die existierende ANSI-Ausgabe zu überschreiben.

Command Blocks

Jeder Befehl und seine Ausgabe wird als eigenständiger Block mit visuellen Trennlinien dargestellt. Rechtsklick auf einen Befehl unter RECENT für Block-Aktionen.

Inline Autocomplete

IDE-artiges Dropdown das beim Tippen erscheint — mit Subcommands, Flags und Beschreibungen.

Eingebaute Completion-Specs für:

Navigieren mit ↑/↓, akzeptieren mit Tab, schließen mit Esc.

Inline-Bilder

Bilder direkt im Terminal anzeigen — über das Kitty Graphics Protocol.

Unterstützt PNG, JPEG, GIF. Nutzt das Kitty-Protokoll mit chunked Base64-Übertragung für große Dateien.

Automatischer Profil-Wechsel

Das Theme wechselt automatisch basierend auf dem Kontext — visuelles Sicherheitsnetz für gefährliche Umgebungen.

Klickbare Pfade & URLs

Dateilinks in der Terminal-Ausgabe öffnen im Relay-Editor; Web-URLs öffnen über macOS. Relay erkennt OSC-8-Links sowie Pfade und URLs in gewöhnlicher Ausgabe, auch wenn diese bereits eingefärbt ist.

Regex-Trigger

Automatische Aktionen wenn Terminal-Output einem Pattern entspricht. Konfigurierbar unter Einstellungen → Notifications → Regex Triggers.

Parametrisierte Snippets

Wiederverwendbare Befehlsvorlagen mit Platzhalter-Parametern. Doppelklick in der Sidebar zum Ausführen.

Beim Ausführen erscheint ein Formular für jeden Platzhalter. Live-Vorschau zeigt den aufgelösten Befehl vor dem Ausführen.

Session Blueprints

Workspace-Layouts als wiederverwendbare Templates speichern. Jeder Blueprint definiert Panes, Startverzeichnisse und Auto-Start-Befehle.

Konfigurierbar unter Einstellungen → Integration → Session Blueprints. Starten über die Sidebar-Sektion BLUEPRINTS.

Pane-Farbmarkierung

Farben per Klick auf die Pane-Namenspille zuweisen. 7 Preset-Farben (Grün, Rot, Gelb, Blau, Lila, Orange, Cyan) zur visuellen Unterscheidung von Umgebungen.

CI/CD Pipeline Monitor

GitHub Actions direkt in Relay überwachen. Der Workspace-Status öffnet die Pipeline-Details mit Jobs und Steps.

Docker-Container

Die Docker-Sektion unter Global listet lokale Container mit Image, Status und gemappten Ports.

Pro Container stehen Start, Stop und Restart als Buttons bereit. Ein Klick auf das Log-Symbol streamt die Container-Logs live ins aktive Terminal; ein Klick auf einen gemappten Port öffnet den Dienst im Browser-Pane.

Relay erkennt, wenn Docker nicht installiert oder der Daemon gestoppt ist, und zeigt einen klaren Hinweis statt einer leeren Liste. Aktualisiert wird nur, solange die Sektion sichtbar ist — keine Hintergrund-Last.

AI-Usage-Dashboard

Relay zeigt vom Anbieter gemeldete Kontingente und Reset-Zeiten. Codex liefert sie über seine CLI-Kontoschnittstelle; Claude über erfasste Limit-Ereignisse aus Relay-gestarteten Läufen.

Das sind keine aus Token-Preisen geschätzten Kosten. Eine manuelle Claude-Aktualisierung führt eine kleine Modellanfrage aus und zählt zum Kontingent. Nicht verfügbare oder veraltete Daten werden entsprechend gekennzeichnet.

Browser-Downloads

Der Browser-Pane unterstützt nutzerinitiierte Downloads: Download-Links landen in einem Download-Manager mit eigener Infopanel-Sektion, PDFs öffnen sich direkt im eingebauten Viewer.

Geräte-Emulation

Der Responsive-Design-Modus rendert die Seite im Browser-Pane in iPhone- und iPad-Rahmen — inklusive Dynamic Island und Home-Indicator. So testest du responsive Layouts, ohne Relay zu verlassen.

Sidebar Cockpit

Workspaces leben in der Titelleiste, Pane-Topologie und Layout-Auswahl im Infopanel rechts (⌘I). Kein Modal, kein Popover — alles bleibt in Sicht.

Inline Workflow

Eingaben dort, wo der Befehl entsteht. Snippets, Pipeline-Logs und Blueprints klappen direkt in der Sidebar auf — mit Live-Preview und Run-Button.

Pipeline Step-Rings

CI/CD-Steps werden als animierte Progress-Ringe angezeigt — kein linearer Balken mehr. Status auf einen Blick erkennbar.

Workspace-Verzeichnis-Inheritance

Wenn du einen Workspace mit einem spezifischen Pfad öffnest, landen alle neuen Splits im selben Projekt — nicht im Home-Verzeichnis.

CardSections & Komponenten

Dein Projekt links. Sein Kontext rechts. Dazwischen Platz zum Arbeiten. Entdecke die Karten, Komponenten und Werkzeuge im Detail.

Browser

⌘3 öffnet den Browser-Slot der aktiven Pane. Mehrere Tabs, Lesezeichen, Verlauf und eine konfigurierbare Suchmaschine sind integriert. Cookies und Website-Daten sind pro Workspace getrennt; der private Modus verwendet einen nicht persistenten Datenspeicher.

Öffne deinen lokalen Dev-Server in einer Browser-Pane neben dem Editor. Automatisches Neuladen beim Speichern lässt sich pro Workspace konfigurieren. Über die Inspector-Schaltfläche öffnest du DevTools für den aktuellen Browser-Tab.

Screenshots erfassen den sichtbaren Ausschnitt oder die ganze Seite, werden in Downloads gespeichert und in die Zwischenablage kopiert. Du findest sie auch unter Global → Browser Shots. ⌘+/⌘− ändern den Seitenzoom; ⌘0 setzt Zoom und Trackpad-Vergrößerung zurück.

Git und Änderungen

Die linke Git-Perspektive zeigt Branches, Änderungen und Staging. Ein Klick auf eine Datei öffnet ihren Diff. Commit, Push und Pull beziehen sich auf den Projektordner des Workspaces.

Git-Aktionen beziehen sich auf den Projektordner des Workspaces. Der lokale Ordnerwechsel im Explorer ändert diesen Projektordner nicht. Bei einem Fehler zeigt Relay die tatsächliche Git-Ausgabe an.

Notizen & To-dos

Links besitzen Notizen und To-dos jeweils ein eigenes Icon. ⌘⇧N öffnet das Planungsfenster bei den Notizen, ⌘⇧T bei den Aufgaben. Im Listenmodus öffnet sich eine Notiz rechts neben der Liste; bei schmalen Fenstern führt „Notizen“ zurück zur Liste. Markdown lässt sich über Stift und Vorschau bearbeiten oder formatiert lesen.

Das Plus im jeweiligen Sidebar-Bereich öffnet eine Inline-Eingabe. Beide Ansichten behalten ihre eigene Suche. Abgehakte Aufgaben bleiben kurz mit grünem Häkchen und Durchstreichung stehen und werden dann ausgeblendet. Über „Erledigte To-dos anzeigen“ kannst du sie prüfen, wieder öffnen oder nach Bestätigung gesammelt löschen. Suche und Filter begrenzen die Löschaktion.

Clipboard Note Capture ist optional. Unter Notes & Todos kannst du festlegen, ob kopierte Texte und Bilder nur aus Relay oder systemweit als Notizen übernommen werden.

Agenten-Dashboard

Die Agentenkarte im Bereich Global zeigt erkannte Läufe, aktive Agenten und wartende Sitzungen. Einzelne Karten lassen sich für weitere Details aufklappen.

Lies die erfasste Aufgabe, letzte Aktivität und geänderte Dateien. Unterstützte Freigaben und Texteingaben beantwortest du in der Karte; alternativ springst du zur verbundenen Sitzung.

Neuen Agenten starten öffnet einen Terminal-Tab für eine konfigurierte CLI. Dafür braucht der aktive Workspace eine Terminal-Pane. Anmeldung und verfügbare Funktionen hängen von deiner Einrichtung ab.

Code-Editor

Jede Pane trägt Terminal, Editor & Co. als Slots — ⌘2 schaltet die aktive Pane auf den Editor um, ⌘1 zurück zum Terminal, der Zustand bleibt erhalten. Datei-Tree links, Editor mit Tabs rechts. Powered by CodeEditSourceEditor (Tree-sitter).

Code-Intelligenz und Dateivorschau

Unter Einstellungen → Editor prüft der Language-Server Doctor verfügbare Server und bietet Installationshilfen. ⌘-Klick springt zur Definition, ⌘⇧E sucht Referenzen. Hover zeigt Dokumentation oder Diagnosemeldungen; Fehler- und Warnungszähler öffnen die Diagnoseliste. Ohne Server verwendet Relay textbasierte Alternativen.

⌘F öffnet Suchen und Ersetzen; ⌘⇧F durchsucht das Projekt. Der Editor zeigt außerdem Bilder, PDFs, SVG, CSV/TSV und Markdown sowie Office-Dateien als schreibgeschützte Vorschau. Git-Markierungen am Rand zeigen lokale Änderungen; die Dateihistorie öffnet frühere Revisionen schreibgeschützt.

Tastenkürzel

Stack Detector

Sobald die aktive Terminal-Pane in einem Git-Repository ist, scannt Relay alle Manifest-Dateien und zeigt die erkannten Stacks in der STACK-Sektion der rechten Sidebar.

Terminal-Suche

Inkrementelle Suche im aktiven Terminal-Buffer mit optionalem Regex-Modus. Die Match-Indikator-Pille zeigt sofort, ob es Treffer gibt.

• Regex-Toggle in der Bar — wechsle zwischen literaler Suche und vollem NSRegularExpression-Pattern
• Eingabefeld färbt rot, wenn keine Treffer mehr im Buffer — kein Rätselraten
• Funktioniert nicht im Alt-Screen-Modus (vim, less, tmux), weil dort die App selbst die Tastatur kontrolliert

Broadcast-Eingabe

Tippe einmal — jeder ausgewählte Pane bekommt die Eingabe parallel. Perfekt für Multi-Server-Operationen, Cluster-Wartung oder Vergleichstests in mehreren Containern.

VPN-Erkennung (geplant)

Geplantes Feature: Relay soll alle `utun*`-Interfaces auf macOS scannen und den aktiven VPN-Provider anhand der Prozessliste identifizieren. Die VPN-Sektion würde nur dann in der Sidebar erscheinen, wenn tatsächlich ein Tunnel aktiv ist — kein Visual-Noise wenn nichts läuft. Dieses Feature ist noch nicht in der aktuellen App enthalten.

Geplante Provider-Erkennung

Geplant: OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cloudflare WARP, Cisco AnyConnect, ExpressVPN, ProtonVPN, Surfshark, PIA, Windscribe, Hotspot Shield, ZeroTier — jeweils über ihren Prozessnamen identifiziert. Noch nicht in der App enthalten.

Polish & Atmosphäre

Kleine Details die den Unterschied machen — von Notifications für lange Befehle bis zum animierten Hintergrund.

Einstellungen

Öffne die Einstellungen mit ⌘,. Die Seiten sind in sechs Bereiche gegliedert. Die folgende Übersicht verwendet die Seitennamen der Oberfläche; über die Suche findest du einzelne Optionen.