Dokumentation

Relay Dokumentation

Alles was du brauchst, um Relay optimal zu nutzen.

Installation

Relay kann als DMG oder via Homebrew installiert werden.

Direkt-Download

Universal Binary für Apple Silicon und Intel.

Download-Seite

Homebrew

brew install --cask relay

Voraussetzungen: macOS 14 Sonoma+, Universal Binary (Apple Silicon & Intel)

Erste Schritte

Nach der Installation bist du in drei Schritten startklar.

Theme wählen

Öffne die Settings und wähle eines der 16 Themes. Das gesamte visuelle System ändert sich sofort.

Prompt-Stil einstellen

Wähle einen der 12 Prompt-Stile. Die Änderung wird live in der aktuellen Shell angewendet.

Workspace einrichten

Erstelle Workspaces für verschiedene Projekte. Jeder Workspace hat eigene Panes, Themes und Layouts.

Tastenkürzel

Die wichtigsten Keyboard Shortcuts für schnelles Arbeiten.

Kürzel	Aktion
`⌘T`	Neuer Pane
`⌘W`	Pane schließen
`⌘D`	Horizontal splitten
`⌘⇧D`	Vertikal splitten
`⌘⌥]`	Nächster Pane
`⌘⌥[`	Vorheriger Pane
`⌘+`	Schrift vergrößern
`⌘−`	Schrift verkleinern
`⌘0`	Schrift zurücksetzen (13)
`⌘I`	Info-Panel ein/aus
`⌘\`	Icon-Rail ein/aus
`⌘P`	Command Palette

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.

Layer 1

AppTheme

Steuert die App-Chrome: Hintergründe, Borders, Akzentfarbe, Glassmorphism, Glow-Effekte.

Layer 2

TerminalTheme

Definiert die ANSI-Farbpalette: 8 Normal- + 8 Bright-Farben, Cursor, Selection, Hintergrund.

Layer 3

PromptStyle

Bestimmt das Prompt-Layout: Symbole, Farben, Powerline-Segmente, Git-Info-Anzeige.

Glass Themes

Sechs moderne Themes mit Glassmorphism, Glow-Effekten und eigener Typografie.

Relay Dark Midnight Aurora Obsidian Sunset Arctic

Retro Themes

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

BBC Micro Apple II Amstrad CPC VT100 Amber IBM 3270 Xerox Alto Game Boy ZX Spectrum Retro DOS C64

Design-Tokens

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

bg · bgElevated · bgTerm · bgTabBar
accent · accentGlow · accentDim
border · borderHi
fg · fgSecond · fgTertiary
glassTint · glassBorder · glassHighlight
scanlines · suggestedFontName · suggestedPromptStyle

Hell/Dunkel-Modus

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

Farb-Schema

Modus	Beschreibung
Dunkel	Verwendet das konfigurierte dunkle Theme (Standard: Relay Dark).
Hell	Verwendet das konfigurierte helle Theme (Standard: Relay Light).
System	Wechselt automatisch zwischen Hell und Dunkel wenn macOS den Modus ändert.

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

Sechs Layout-Presets ermöglichen es, einen Workspace in bis zu 4 Panes aufzuteilen. Layouts werden pro Workspace gespeichert.

Layout	Panes	Beschreibung
`Single`	1	Standard — ein einzelner Pane
`2 Side`	2	Zwei Panes nebeneinander
`2 Stack`	2	Zwei Panes übereinander
`1+2`	3	Ein großer Pane links, zwei kleine rechts
`2×2`	4	Vier Panes im 2×2-Raster
`Focus`	2	Ein fokussierter Pane, ein gedimmter Sekundär-Pane

Layouts werden automatisch angepasst: Beim Hinzufügen eines Panes wird das Layout upgraded, beim Entfernen downgraded.

Prompt-Stile

11 integrierte Prompt-Stile — direkt in den Settings wählbar, sofort live angewendet. Keine .zshrc-Bearbeitung nötig.

Stil	Herkunft	Powerline
Relay Compact	Built-in	—
Robbyrussell	Oh My Zsh	—
Bureau	Oh My Zsh	—
Minimal	Built-in	—
Bira	Oh My Zsh	—
Lambda	Oh My Zsh	—
Powerblocks	Built-in	✓
Agnoster	Plugin	✓
Spaceship	Plugin	—
Powerlevel10k	Plugin	✓
Starship	Extern (Rust)	—

Powerline-Stile benötigen einen Nerd Font. Relay verwendet standardmäßig JetBrains Mono Nerd Font.

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.

~/.config/relay/memory/<hash>.json

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

Shell	Integration	Hooks
`zsh`	ZDOTDIR → `~/.config/relay/`	precmd / preexec
`bash`	--rcfile `~/.config/relay/.bashrc`	PROMPT_COMMAND + DEBUG trap
`fish`	-C source `~/.config/relay/fish/`	fish_preexec / fish_postexec

OSC-Sequenzen

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

OSC	Funktion
`OSC 133;A`	Prompt-Start
`OSC 133;B`	Befehl-Start (Nutzer tippt)
`OSC 133;C`	Ausgabe-Start (Befehl abgeschickt)
`OSC 133;D;exit`	Befehl beendet mit Exit-Code
`OSC 7`	Aktuelles Arbeitsverzeichnis
`OSC 1337`	iTerm2-Kompatibilität (CurrentDir)
`OSC 9999;ask`	Relay-Befehle (ask, save)

Shell-Modi

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

Relay Prompt

Isolierte Shell-Konfiguration. Relay verwaltet den Prompt vollständig. Ideal für konsistentes Verhalten.

User .zshrc

Lädt die eigene ~/.zshrc mit Relay-Hooks. Kompatibel mit oh-my-zsh, p10k und Starship.

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 auf das Badge terminiert die aktuelle Shell und startet sie sofort mit dem anderen Modus neu
Jeder Pane behält seinen eigenen Modus — unabhängig von anderen Panes und der globalen Einstellung

Info-Panel

Das Info-Panel (⌘I) zeigt kontextbezogene Informationen zum aktiven Workspace und Pane.

Project Memory

Zeigt den aktuellen Projektkontext: Pfad, Git-Branch, Runtime. Persistent zwischen Sessions.

Recent Commands

Die letzten 5 Befehle mit Exit-Code-Badge (grün/rot/orange) und Zeitstempel.

Favorites

Favorisierte Befehle und Verzeichnisse. Per Stern-Icon markierbar, persistent gespeichert.

Working Directories

Verlauf der besuchten Verzeichnisse. Klick navigiert sofort dorthin.

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

Relay erkennt aktive VPN-Tunnel (OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cisco AnyConnect und 14+ weitere Provider) und zeigt Interface, IP und Provider im Info-Panel.

AI Agent

Der integrierte AI Agent beantwortet Fragen direkt im Terminal. Er kennt den Shell-Kontext (letzte Befehle, CWD, Ausgaben) und kann gezielt helfen.

Verwendung

relay ask "Was macht dieser Befehl?"

Provider

Provider	Modelle
OpenAI	gpt-4o-mini, gpt-4, gpt-4o
Anthropic	claude-haiku-4-5, claude-sonnet, claude-opus

Slash-Commands

Befehl	Beschreibung
`/help`	Hilfe anzeigen
`/save`	Gespräch speichern
`/clear`	Verlauf löschen
`/model`	Modell wechseln
`/copy`	Letzte Antwort kopieren
`/context`	Shell-Kontext anzeigen
`/run`	Befehl ausführen
`/tokens`	Token-Verbrauch anzeigen
`/exit`	Agent beenden

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 auf 'Explain?' sendet 'relay explain' an die Shell — der AI-Agent erklärt den letzten Befehl
Erfordert einen konfigurierten AI-Provider (Anthropic oder OpenAI) 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.

Muster	Farbe	Beispiel
Fehler	Rot (fett)	`error, fatal, exception`
Warnungen	Gelb	`warning, deprecated`
Erfolg	Grün	`OK, Done, PASSED, ✓`
URLs	Blau (unterstrichen)	`https://...`
Pfade	Cyan	`/usr/local/bin`
IPv4	Gelb	`192.168.1.1`
Zahlen + Einheiten	Magenta	`340ms, 18.4MB`

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.

│

Visuelle Trennlinien

Dezente Gradient-Linien zwischen Befehlen machen das Terminal auf einen Blick übersichtlich.

⧉

Block-Aktionen

Rechtsklick unter RECENT → Output kopieren, erneut ausführen, zum Block scrollen, Favorit hinzufügen.

⌘⇧↑

Block-Navigation

⌘⇧↑ / ⌘⇧↓ zum Springen zwischen Command-Blocks.

Inline Autocomplete

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

git commit --message, --amend, --all, --no-edit...

Eingebaute Completion-Specs für:

git docker npm cargo brew

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

Inline-Bilder

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

relay imgcat ~/Desktop/photo.png

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.

🔴

SSH

SSH-Verbindungen wechseln zu einem Warn-Theme (z.B. Obsidian). Konfigurierbar pro Host-Pattern.

📁

Verzeichnis-Regeln

Theme wechselt beim Betreten bestimmter Verzeichnisse. Matching mit Regex-Patterns.

Klickbare Pfade & URLs

Dateipfade und URLs in der Terminal-Ausgabe sind klickbar. ⌘+Klick zum Öffnen — Pfade öffnen im Finder, URLs im Browser. Nutzt den OSC 8 Hyperlink-Standard.

⌘+Click → /usr/local/bin/node → opens in Finder

Regex-Trigger

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

🔔

Benachrichtigungen

macOS-Benachrichtigung wenn Output matcht (z.B. 'BUILD SUCCEEDED').

🔊

Sound

Sound abspielen bei Pattern-Match (z.B. 'BUILD FAILED').

Parametrisierte Snippets

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

deploy {{service}} to {{env}}

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 Rechtsklick auf den Pane-Header 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. Nach git push erscheint der Pipeline-Status live in der Sidebar.

⚡

Auto-Erkennung

Erkennt git push aus jeder Shell (Relay, externes Terminal, IDE) über Filesystem-Überwachung.

📊

Live-Updates

Steps aktualisieren sich alle 5 Sekunden mit animierter Fortschrittsanzeige und pulsierenden Status-Dots.

📋

Job-Logs

Klick auf einen Step zeigt die Logs in einem Popover. Logs mit einem Klick in die Zwischenablage kopieren.

Settings → CI/CD Pipeline → GitHub Token

Einstellungen

Relay organisiert 40+ Einstellungen in 7 Seiten. Alle Settings werden in UserDefaults gespeichert und sind sofort wirksam. Gruppen: Allgemein (Erscheinungsbild, Tastatur) · Terminal (Shell & Umgebung, Benachrichtigungen) · Erweitert (Speicher & Sessions, Shell Integration, KI-Assistent).

Seite 1: Erscheinungsbild

Theme, Farb-Schema, Font, Cursor, Transparenz und Semantic Highlighting — alles auf einer Seite.

Einstellung	Standard	Beschreibung
`colorSchemeEnabled`	false	Auto-Erscheinungsbild aktivieren (Hell/Dunkel/System)
`colorScheme`	dark	Modus: dark · light · auto (folgt macOS)
`appThemeID`	relay-dark	App-Theme (17 Themes: 7 Glass + 10 Retro)
`themeID`	dark-default	Terminal-Farbpalette (ANSI-Farben)
`promptStyleID`	robbyrussell	Prompt-Stil (11 Stile)
`fontSize`	13	Schriftgröße (8–32)
`fontName`	JetBrains Mono Nerd	Schriftart (Nerd Font empfohlen)
`backgroundOpacity`	0.7	Hintergrund-Transparenz
`semanticHighlighting`	true	Automatische Einfärbung von Fehlern, Pfaden, URLs
`cursorShape`	block	block · bar · underline
`cursorBlink`	true	Cursor-Blinken ein/aus
`cursorColorHex`	#4af09a	Cursor-Farbe (Hex)

Seite 2: Tastatur

Übersicht aller 20 Tastenkürzel — von ⌘T (neuer Tab) bis ⌘0 (Schrift zurücksetzen).

Seite 3: Shell & Umgebung

Shell-Programm, Login-Modus, Startup-Verzeichnis, ENV-Variablen und PATH-Erweiterungen.

Einstellung	Standard	Beschreibung
`shellPath`	$SHELL	Shell-Pfad (automatisch erkannt)
`shellLoginMode`	true	Login-Shell (-l Flag)
`shellArgs`	—	Zusätzliche Shell-Argumente beim Start
`useUserZshrc`	false	Eigene .zshrc verwenden
`optionAsMeta`	false	Option-Taste als Meta
`inheritSystemEnv`	true	System-Umgebung erben (Standard: aktiviert)
`pathExtensions`	—	PATH-Erweiterungen (werden am Anfang eingefügt)
`autoLoadDotenv`	false	Automatisches Laden von .env-Dateien im Arbeitsverzeichnis

Seite 4: Benachrichtigungen

Bell-Verhalten, Langzeit-Command-Benachrichtigungen und Webhook-Integration.

Einstellung	Standard	Beschreibung
`audibleBell`	false	System-Sound bei Terminal-Bell
`visualBell`	true	Kurzes Aufblinken des Terminals bei Bell
`notifyLongCommand`	true	Benachrichtigung bei Commands > N Sekunden (nur im Hintergrund)
`webhookURL`	—	POST-Request an eigene URL bei Command-Ende

Seite 5: Speicher & Sessions

Project Memory, Session-Persistenz, Backup und Broadcast-Steuerung.

Einstellung	Standard	Beschreibung
`projectMemoryEnabled`	true	Project Memory aktivieren (Kontext pro Verzeichnis)
`projectMemoryRetention`	30 Tage	Aufbewahrung: 7 Tage · 30 Tage · Unbegrenzt
`saveTabsOnQuit`	true	Tabs beim Beenden speichern
`restoreWorkspacesOnLaunch`	true	Workspaces beim Start wiederherstellen

Seite 6: Shell Integration

Optionales Shell-Script das präzises Command-Tracking über OSC 133/7 ermöglicht. Kann ein-/ausgeschaltet werden.

Seite 7: KI-Assistent

Provider-Auswahl (Anthropic/OpenAI), API Keys, Modell-Konfiguration und Kontext-Steuerung.

Einstellung	Standard	Beschreibung
`aiEnabled`	false	KI-Assistent aktivieren (relay ask / relay explain)
`aiProvider`	anthropic	Provider: anthropic · openai
`aiContextLines`	50	Anzahl Shell-History-Zeilen als Kontext (0 = kein Kontext)

Relay-spezifische Variablen

RELAY_PROMPT_STYLE # Aktiver Prompt-Stil
RELAY_AI_PROVIDER # AI-Provider (anthropic/openai)
RELAY_AI_API_KEY # API-Schlüssel
RELAY_AI_MODEL # Modell-ID
RELAY_AI_CONTEXT # Shell-Kontext für AI

Relay Dokumentation

Installation

Direkt-Download

Homebrew

Erste Schritte

Theme wählen

Prompt-Stil einstellen

Workspace einrichten

Tastenkürzel

Theme-System

Drei-Ebenen-Architektur

AppTheme

TerminalTheme

PromptStyle

Glass Themes

Retro Themes

Design-Tokens

Hell/Dunkel-Modus

Farb-Schema

Pane-Layouts

Prompt-Stile

Workspaces

Project Memory

Speicherort

Shell-Integration

Unterstützte Shells

OSC-Sequenzen

Shell-Modi

Relay Prompt

User .zshrc

Per-Pane Shell-Modus

Info-Panel

Project Memory

Recent Commands

Favorites

Working Directories

Offene Ports

VPN-Erkennung

AI Agent

Verwendung

Provider

Slash-Commands

Automatisches Error-Explain

Semantic Colorizer

Command Blocks

Inline Autocomplete

Inline-Bilder

Automatischer Profil-Wechsel

Klickbare Pfade & URLs

Regex-Trigger

Parametrisierte Snippets

Sticky Command Header

Session Blueprints

Pane-Farbmarkierung

CI/CD Pipeline Monitor

Einstellungen

Seite 1: Erscheinungsbild

Seite 2: Tastatur

Seite 3: Shell & Umgebung

Seite 4: Benachrichtigungen

Seite 5: Speicher & Sessions

Seite 6: Shell Integration

Seite 7: KI-Assistent

Relay-spezifische Variablen