Relay Documentation
Everything you need to get the most out of Relay.
Installation
Relay can be installed as a DMG or via Homebrew.
Homebrew
brew install --cask relayFirst Steps
After installation, you're ready in three steps.
Choose a theme
Open Settings and pick one of 19 themes. The entire visual system changes instantly.
Set your prompt style
Choose one of 9 prompt styles. The change is applied live to the current shell.
Set up workspaces
Create workspaces for different projects. Each workspace has its own panes, themes, and layouts.
Keyboard Shortcuts
Essential keyboard shortcuts for fast workflows.
| Shortcut | Action |
|---|---|
| ⌘K | Open command palette |
| ⌘D | Split pane horizontally |
| ⌘⇧D | Split pane vertically |
| ⌘W | Close active pane |
| ⌘⌥] | Focus next pane |
| ⌘⌥[ | Focus previous pane |
| ⌘1 | Active pane → Terminal |
| ⌘2 | Active pane → Editor |
| ⌘3 | Active pane → Browser |
| ⌘4 | Active pane → AI chat |
| ⌘5 | Active pane → Scratch pad |
| ⌘I | Toggle info panel |
| ⌘⌥A | Global Ask — query AI from any pane |
| ⌘⇧↑ | Jump to previous command block |
| ⌘⇧↓ | Jump to next command block |
| ⌘+ / ⌘− | Increase / decrease font size |
| ⌘0 | Reset font size to default |
Theme System
Relay's theme system consists of three layers that together control the entire look and feel of the app.
Three-Layer Architecture
Each theme is composed of three independent layers that work together.
AppTheme
Controls the app chrome: backgrounds, borders, accent color, glassmorphism, glow effects.
TerminalTheme
Defines the ANSI color palette: 8 normal + 8 bright colors, cursor, selection, background.
PromptStyle
Determines the prompt layout: symbols, colors, powerline segments, git info display.
Glass Themes
Six modern themes with glassmorphism, glow effects, and unique typography.
Retro Themes
Eight historical terminals (1973–1989) as complete visual identities with scanlines and period-accurate fonts.
Design Tokens
Each theme defines 93 design tokens that control the entire visual appearance.
bg · bgElevated · bgTerm · bgTabBar
accent · accentGlow · accentDim
border · borderHi
fg · fgSecond · fgTertiary
glassTint · glassBorder · glassHighlight
scanlines · suggestedFontName · suggestedPromptStyleLight/Dark Mode
Relay supports a light and a dark theme with automatic switching based on macOS system appearance.
Color Scheme
| Mode | Description |
|---|---|
| Dark | Uses the configured dark theme (default: Relay Dark). |
| Light | Uses the configured light theme (default: Relay Light). |
| System | Automatically switches between light and dark when macOS changes appearance. |
Configure the mode in Settings → Appearance → Color Scheme. In System mode, Relay observes the macOS appearance and switches themes instantly.
Pane Layouts
Nine layout presets let you split a workspace into up to 4 panes. Layouts are saved per workspace.
| Layout | Panes | Description |
|---|---|---|
Single | 1 | Default — a single pane |
2 Side | 2 | Two panes side by side |
2 Stack | 2 | Two panes stacked |
3 Side | 3 | Three equal-width panes side by side |
4 Side | 4 | Four equal-width panes side by side |
1+2 | 3 | One large pane left, two small on the right |
1+3 | 4 | One large pane left, three small on the right |
2×2 | 4 | Four panes in a 2×2 grid |
Focus | 2 | One focused pane, one dimmed secondary pane |
Prompt Styles
9 prompt styles — 5 built-in in Relay-managed mode (Relay Compact, Robbyrussell, Minimal, Lambda, Powerblocks), 4 external in “Your ~/.zshrc” mode (Agnoster, Spaceship, Powerlevel10k, Starship).
| Style | Origin | Powerline |
|---|---|---|
| Relay Compact | Built-in | — |
| Robbyrussell | Built-in | — |
| Minimal | Built-in | — |
| Lambda | Built-in | — |
| Powerblocks | Built-in | ✓ |
| Agnoster | External (Rust) | ✓ |
| Spaceship | External (Rust) | — |
| Powerlevel10k | External (Rust) | ✓ |
| Starship | External (Rust) | — |
Workspaces
Workspaces are isolated environments with their own state. Each workspace stores:
- Its own theme and terminal color palette
- Its own pane layout (Single, 2×2, Focus, etc.)
- Its own panes with individual shells
- Persistence between sessions (tabs, CWD, layout)
- Broadcast mode: send input to multiple panes at once
- Optional custom shell path per workspace
Project Memory
Relay persists per-project context to disk. Commands, directories, and usage frequency survive across sessions.
- Commands are deduplicated per project — stored with use count and last exit code
- Visited directories are tracked with visit count and timestamp
- Retention is configurable: 7 days, 30 days, or unlimited
- Most-used commands appear in the sidebar under 'Project History'
Storage
One JSON file per project is stored under the configured path (default: ~/.config/relay/memory/). Max 500 commands and 200 directories per project.
~/.config/relay/memory/<hash>.jsonOn app launch, old entries are automatically pruned based on the retention setting. Empty project files are removed.
Shell Integration
Relay integrates deeply with the shell to track commands, exit codes, and working directories. The integration is installed automatically on every launch.
Supported 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 Sequences
Relay uses Operating System Command (OSC) sequences for communication between shell and app.
| OSC | Purpose |
|---|---|
OSC 133;A | Prompt start |
OSC 133;B | Command start (user typing) |
OSC 133;C | Output start (command submitted) |
OSC 133;D;exit | Command finished with exit code |
OSC 7 | Current working directory |
OSC 1337 | iTerm2 compatibility (CurrentDir) |
OSC 9999;ask | Relay commands (ask, save) |
Shell Modes
Relay offers two modes for shell configuration.
Relay Prompt
Isolated shell configuration. Relay manages the prompt entirely. Ideal for consistent behavior.
User .zshrc
Loads your own ~/.zshrc with Relay hooks. Compatible with oh-my-zsh, p10k, and Starship.
Per-Pane Shell Mode
Each pane can individually switch between Relay prompt and user zshrc — directly in the pane header, without opening settings.
- A badge in the pane header shows the active mode: 'relay' (terminal icon) or 'zshrc' (person icon)
- Clicking the badge terminates the current shell and relaunches it with the other mode immediately
- Each pane keeps its own mode — independent of other panes and the global setting
Info Panel
The Info Panel (⌘I) shows contextual information about the active workspace and pane.
Project Memory
Shows the current project context: path, git branch, runtime. Persistent between sessions.
Recent Commands
The last 5 commands with exit code badge (green/red/orange) and timestamp.
Favorites
Favorited commands and directories. Marked via star icon, persistently stored.
Working Directories
History of visited directories. Click to navigate there instantly.
Open Ports
Relay automatically detects open ports and their associated processes on the system.
- Automatic detection of all listening TCP ports
- Display of port, process name, and PID
- Process tree kill per click (getpgid + SIGKILL)
- Sudo fallback for insufficient permissions (copies command to clipboard)
VPN Detection
Relay detects active VPN tunnels (OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cisco AnyConnect and 14+ more providers) and shows interface, IP, and provider in the Info Panel.
AI Agent
The built-in AI agent answers questions right in the terminal. It knows the shell context (recent commands, CWD, output) and can help with targeted assistance.
Usage
relay ask "What does this command do?"Providers
| Provider | Models |
|---|---|
| OpenAI | gpt-4o-mini, gpt-4, gpt-4o |
| Anthropic | claude-haiku-4-5, claude-sonnet, claude-opus |
Slash Commands
| Command | Description |
|---|---|
/help | Show help |
/save | Save conversation |
/clear | Clear history |
/model | Switch model |
/copy | Copy last response |
/context | Show shell context |
/run | Execute command |
/tokens | Show token usage |
/exit | Exit agent |
Automatic Error Explain
When a command exits with a non-zero exit code, Relay offers to have the AI agent explain the error.
- Failed commands show a red dot and an 'Explain?' badge in the sidebar on hover
- Clicking 'Explain?' sends 'relay explain' to the shell — the AI agent explains the last command
- Requires a configured AI provider (Anthropic or OpenAI) in settings
Semantic Colorizer
Relay automatically colorizes terminal output: errors, warnings, URLs, paths, and numbers get context-aware colors — without overwriting existing ANSI output.
| Pattern | Color | Example |
|---|---|---|
| Errors | Red (bold) | error, fatal, exception |
| Warnings | Yellow | warning, deprecated |
| Success | Green | OK, Done, PASSED, ✓ |
| URLs | Blue (underline) | https://... |
| Paths | Cyan | /usr/local/bin |
| IPv4 | Yellow | 192.168.1.1 |
| Numbers + Units | Magenta | 340ms, 18.4MB |
Command Blocks
Every command and its output is treated as a discrete block with visual separators. Right-click any command in RECENT for block actions.
Subtle gradient lines between commands make the terminal scannable at a glance.
Right-click in RECENT → Copy Output, Re-run, Scroll to Block, Add Favorite.
⌘⇧↑ / ⌘⇧↓ to jump between command blocks.
Inline Autocomplete
IDE-style dropdown that appears as you type, showing subcommands, flags, and descriptions.
Built-in completion specs for:
Navigate with ↑/↓, accept with Tab, dismiss with Esc.
Inline Images
Display images directly in the terminal using the Kitty Graphics Protocol.
Supports PNG, JPEG, GIF. Uses Kitty protocol with chunked base64 transmission for large files.
Automatic Profile Switching
Theme changes automatically based on context — visual safety net for dangerous environments.
SSH connections switch to a warning theme (e.g., Obsidian). Configurable per host pattern.
Switch theme when entering specific directories. Match with regex patterns.
Clickable Paths & URLs
File paths and URLs in terminal output are clickable. ⌘+Click to open — paths open in Finder, URLs in your browser. Uses the OSC 8 hyperlink standard.
Regex Triggers
Automatic actions when terminal output matches a pattern. Configure in Settings → Appearance → Regex Triggers.
macOS notification when output matches (e.g., 'BUILD SUCCEEDED').
Play a sound on pattern match (e.g., 'BUILD FAILED').
Parameterized Snippets
Reusable command templates with placeholder parameters. Double-click in the sidebar to run.
When executed, a form appears for each placeholder. Live preview shows the resolved command before running.
Sticky Command Header
When a command produces long output, its name stays pinned at the top of the terminal with an elapsed timer. You always know what's running.
Session Blueprints
Save workspace layouts as reusable templates. Each blueprint defines panes, starting directories, and auto-start commands.
Configure in Settings → Integration → Session Blueprints. Launch from the sidebar BLUEPRINTS section.
Pane Coloring
Assign colors to panes via right-click on the pane header. Choose from 7 preset colors (green, red, yellow, blue, purple, orange, cyan) to visually distinguish environments.
CI/CD Pipeline Monitor
Monitor GitHub Actions directly in Relay. After git push, the pipeline status appears live in the sidebar.
Detects git push from any shell (Relay, external terminal, IDE) via filesystem watching.
Steps update every 5 seconds with animated progress bar and pulsing status dots.
Click any step to expand its log inline below. Copy logs to clipboard with one click.
Sidebar Cockpit
Workspaces, pane topology, and layout selection live in the right sidebar. No modal, no popover — everything stays in view.
List of all open workspaces with a colored dot, pane count (e.g. "4p"), and activity indicator when a pane has a running command. Click activates; right-click → Close.
Per pane: pulsing running indicator, current or last command, exit-code badge (✓ / failure code / ⌃C), and shell-mode toggle (Relay prompt ↔ ~/.zshrc). Drag-to-swap between slots.
Header pill shows the current layout (e.g. "2×2 ▾"). Click to expand 6 topology thumbnails: Single, 2 Side, 2 Stack, 1+2, 2×2, Focus.
The collapsed left sidebar shows the first letter of each workspace as a badge — instead of anonymous dots. "bunni" → "B", "T1" → "T".
Inline Workflow
Inputs where the command happens. Snippets, pipeline logs, and blueprints expand right inside the sidebar — with live preview and a run button.
Parameterized snippets expand with inline inputs. Live-resolved preview shows the final command. Run button is disabled while parameters are empty — no broken commands.
Click a CI/CD step to expand its log directly below. Scrollable, selectable, with copy button.
Pick pane directories via the native macOS dialog instead of typing them. Paths are stored home-relative (~/project) for cross-machine portability.
Pipeline Step Rings
CI/CD steps render as animated progress rings — no more linear bars. Status legible at a glance.
Yellow spinner ring (72% filled) rotates continuously. Linear, 1.2 seconds per turn.
Full green ring with a checkmark in the center. Instantly recognizable in the step list.
Full red ring with an X in the center. Plus red step name for extra visibility.
Workspace directory inheritance
When you open a workspace at a specific path, every new split lands in the same project — not the home directory.
⌘D and ⌘⇧D open new panes in the workspace root path. If you `cd` somewhere else inside a pane, it doesn't affect the next split.
Blueprints inherit the first pane's path as the workspace root. Later splits inside a blueprint-launched workspace land there too.
When a blueprint has more panes than the chosen layout allows (e.g. "single" with 4 BlueprintPanes), the layout auto-upgrades to one that fits (twoByTwo).
Code Editor (v1.2)
Any terminal pane converts into a code editor via right-click → "Convert to editor". File tree on the left, tabbed editor on the right. Powered by CodeEditSourceEditor (tree-sitter).
Right-click on the pane label → "Convert to editor". Reverse with "Convert to terminal". The folder root is the git repo root of the current cwd.
Languages are auto-detected by file extension. Supported: Swift, TS/JS/TSX, Rust, Python, Go, Ruby, Java, Kotlin, C/C++, JSON, TOML, YAML, Markdown, Shell, CSS, HTML, SQL, Dockerfile and many more.
Multiple files open at once. Tab bar with dirty indicator. Cursor and scroll position survive per file across tab switches.
Right-click an entry: Reveal in Finder, Copy Path, New File, New Folder, Rename, Duplicate, Move to Trash. Input sheets for names, trash with confirmation.
Word completion from buffer identifiers plus per-language keyword lists (Swift, TS/JS, Rust, Python, Go, Ruby, Java, Kotlin, Bash, CSS). Auto-triggered on every letter.
Relay Dark, Relay Light, Solarized Dark, Nord, Monokai, GitHub Light — all with authentic brand colors. Configurable in Settings → Code Editor → Theme.
Keyboard shortcuts
| Key | Action |
|---|---|
| ⌘S | Save active file |
| ⌘W | Close active tab |
| ⌘1–⌘9 | Jump to tab N |
| ⌘F | Open find & replace |
Stack Detector (v1.2)
As soon as the active terminal pane is inside a git repository, Relay scans all manifest files and shows detected stacks in the STACK section of the right sidebar.
Uses `git ls-files --cached --others --exclude-standard` for the file list — all .gitignore rules are honored correctly. Tool folders like `.github`, `.vscode`, `node_modules` are additionally filtered.
Node.js (package.json), Rust (Cargo.toml), Python (pyproject.toml/requirements.txt), Go (go.mod), Swift (Package.swift/xcodeproj), Ruby (Gemfile), Docker (Dockerfile/compose), Hugo, Jekyll, Zola, mdBook, Supabase.
For Node.js: Next.js, Nuxt, Astro, SvelteKit, Remix, Gatsby, Eleventy, Qwik, Solid, Vue, React, Angular, Tauri, Electron, Vite and more. For Python: FastAPI, Django, Flask, Streamlit, PyTorch.
Workspace markers (pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, Cargo [workspace]) are handled specially. Otherwise every subdirectory stack appears as its own card.
Every detected script appears with a ▶ button. Click writes the command into the active terminal pane — with a `cd <subdir>` prefix in multi-stack repos.
Terminal search
Incremental search over the active terminal buffer with an optional regex mode. The match indicator pill shows immediately whether there are any hits.
| Key | Action |
|---|---|
| ⌘F | Open / close the search bar |
| ⌘G | Next match |
| ⌘⇧G | Previous match |
| Esc | Close search |
- Regex toggle in the bar — switch between literal search and full NSRegularExpression patterns
- Input field turns red when there are no matches left in the buffer — no guesswork
- Doesn't work in alt-screen mode (vim, less, tmux), because the app there owns the keyboard
Broadcast input
Type once — every selected pane gets the input in parallel. Perfect for multi-server operations, cluster maintenance, or comparative tests across containers.
Toggle in the workspace sidebar — the BROADCAST section appears and lists every pane in the workspace with a checkbox.
Use checkboxes to pick which panes receive input. On enable all panes are pre-selected; deselect individual ones as needed.
SSH to four servers, run `apt update` once. Inspect three Docker containers in parallel. Pull multiple branches at the same time.
VPN detection
Relay scans all `utun*` interfaces on macOS and identifies the active VPN provider via the process list. The VPN section only appears in the sidebar when a tunnel is actually up — no visual noise when nothing's running.
Supported providers (14+)
OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cloudflare WARP, Cisco AnyConnect, ExpressVPN, ProtonVPN, Surfshark, PIA, Windscribe, Hotspot Shield, ZeroTier — all identified by their process name.
What's shown
Tunnel interface (utun0/utun1/…), assigned local IP, provider name with status badge.
When visible
Only when at least one utun interface is up and its owning process is running. Auto-refreshes on cwd change.
Polish & atmosphere
Small details that make the difference — from notifications for long-running commands to the animated background.
When a program sends `BEL` (e.g. `printf '\a'` or on tab-completion conflict), the pane flashes white briefly. Optional system sound. Configurable per workspace.
Commands taking longer than N seconds (default 30s) trigger a macOS notification when they finish — even if Relay is in the background. No more staring at the screen.
Optionally configure a webhook URL (Slack, Discord, ntfy.sh, …). Long commands also fire to that URL — perfect for builds running in the office while you're at lunch.
Animated mesh gradient with four colored blobs behind the window. 30 FPS via Canvas + drawingGroup() (GPU-accelerated). Color matches the active app theme.
Retro themes get scanlines (Off/Light/Medium/Heavy configurable), a subtle edge vignette, and chromatic-aberration color fringes. Pure retro vibes, performance-neutral.
Relay updates itself automatically — new versions appear with a changelog preview and install button. Check manually via menu "Relay → Check for Updates".
Settings
Relay organizes all settings into 11 pages. All settings are stored in UserDefaults and take effect immediately. Groups: Appearance (Look & Feel, Keyboard) · Environment (Shell, Notifications) · Panes (Editor, Browser) · Power Tools (Memory, Integration, AI, Pipeline) · Account (License).
Page 1: Appearance
Theme, color scheme, font, cursor, transparency, and semantic highlighting — all on one page.
| Setting | Default | Description |
|---|---|---|
colorSchemeEnabled | false | Enable auto appearance (Light/Dark/System) |
colorScheme | dark | Mode: dark · light · auto (follows macOS) |
appThemeID | relay-dark | App theme (19 themes: 11 modern + 8 retro) |
themeID | dark-default | Terminal color palette (ANSI colors) |
promptStyleID | robbyrussell | Prompt style (11 styles) |
fontSize | 13 | Font size (8–32) |
fontName | JetBrains Mono Nerd | Font family (Nerd Font recommended) |
backgroundOpacity | 0.7 | Background opacity |
semanticHighlighting | true | Auto-colorize errors, paths, URLs |
cursorShape | block | block · bar · underline |
cursorBlink | true | Cursor blinking on/off |
cursorColorHex | #4af09a | Cursor color (hex) |
Page 2: Keyboard
Overview of all 20 keyboard shortcuts — from ⌘T (new tab) to ⌘0 (reset font).
Page 3: Shell & Environment
Shell program, login mode, startup directory, environment variables, and PATH extensions.
| Setting | Default | Description |
|---|---|---|
shellPath | $SHELL | Shell path (auto-detected) |
shellLoginMode | true | Login shell (-l flag) |
shellArgs | — | Additional shell arguments at launch |
useUserZshrc | false | Use own .zshrc |
optionAsMeta | false | Option key as Meta |
inheritSystemEnv | true | Inherit system environment (default: enabled) |
pathExtensions | — | PATH extensions (prepended to PATH) |
autoLoadDotenv | false | Auto-load .env files in the working directory |
Page 4: Notifications
Bell behavior, long-running command notifications, and webhook integration.
| Setting | Default | Description |
|---|---|---|
audibleBell | false | System sound on terminal bell |
visualBell | true | Brief flash on terminal bell |
notifyLongCommand | true | Notify on commands > N seconds (background only) |
webhookURL | — | POST request to custom URL on command finish |
Page 5: Storage & Sessions
Project memory, session persistence, backup, and broadcast controls.
| Setting | Default | Description |
|---|---|---|
projectMemoryEnabled | true | Enable project memory (per-directory context) |
projectMemoryRetention | 30 Tage | Retention: 7 days · 30 days · Unlimited |
saveTabsOnQuit | true | Save tabs on quit |
restoreWorkspacesOnLaunch | true | Restore workspaces on launch |
Page 6: Shell Integration
Optional shell script enabling precise command tracking via OSC 133/7. Can be toggled on/off.
Page 7: AI Assistant
Provider selection (Anthropic/OpenAI), API keys, model configuration, and context control.
| Setting | Default | Description |
|---|---|---|
aiEnabled | false | Enable AI assistant (relay ask / relay explain) |
aiProvider | anthropic | Provider: anthropic · openai |
aiContextLines | 50 | Number of shell history lines as context (0 = no context) |
Relay-specific Variables
RELAY_PROMPT_STYLE # Active prompt style
RELAY_AI_PROVIDER # AI provider (anthropic/openai)
RELAY_AI_API_KEY # API key
RELAY_AI_MODEL # Model ID
RELAY_AI_CONTEXT # Shell context for AI