Relay Documentation

Everything you need to get the most out of Relay.

Installation

Relay can be installed as a DMG or via Homebrew.

Direct Download

Universal Binary for Apple Silicon and Intel.

Download Page

Homebrew

brew install --cask relay
Requirements: macOS 15 Sequoia+, Universal Binary (Apple Silicon & Intel)

First Steps

After installation, you're ready in three steps.

1

Choose a theme

Open Settings and pick one of 19 themes. The entire visual system changes instantly.

2

Set your prompt style

Choose one of 9 prompt styles. The change is applied live to the current shell.

3

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.

ShortcutAction
⌘KOpen command palette
⌘DSplit pane horizontally
⌘⇧DSplit pane vertically
⌘WClose active pane
⌘⌥]Focus next pane
⌘⌥[Focus previous pane
⌘1Active pane → Terminal
⌘2Active pane → Editor
⌘3Active pane → Browser
⌘4Active pane → AI chat
⌘5Active pane → Scratch pad
⌘IToggle info panel
⌘⌥AGlobal Ask — query AI from any pane
⌘⇧↑Jump to previous command block
⌘⇧↓Jump to next command block
⌘+ / ⌘−Increase / decrease font size
⌘0Reset 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.

Layer 1

AppTheme

Controls the app chrome: backgrounds, borders, accent color, glassmorphism, glow effects.

Layer 2

TerminalTheme

Defines the ANSI color palette: 8 normal + 8 bright colors, cursor, selection, background.

Layer 3

PromptStyle

Determines the prompt layout: symbols, colors, powerline segments, git info display.

Glass Themes

Six modern themes with glassmorphism, glow effects, and unique typography.

Relay Dark Midnight Aurora Obsidian Sunset Arctic

Retro Themes

Eight historical terminals (1973–1989) as complete visual identities with scanlines and period-accurate fonts.

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

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 · suggestedPromptStyle

Light/Dark Mode

Relay supports a light and a dark theme with automatic switching based on macOS system appearance.

Color Scheme

ModeDescription
DarkUses the configured dark theme (default: Relay Dark).
LightUses the configured light theme (default: Relay Light).
SystemAutomatically 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.

LayoutPanesDescription
Single1Default — a single pane
2 Side2Two panes side by side
2 Stack2Two panes stacked
3 Side3Three equal-width panes side by side
4 Side4Four equal-width panes side by side
1+23One large pane left, two small on the right
1+34One large pane left, three small on the right
2×24Four panes in a 2×2 grid
Focus2One focused pane, one dimmed secondary pane
Layouts auto-adjust: adding a pane upgrades the layout, removing one downgrades it.

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).

StyleOriginPowerline
Relay CompactBuilt-in
RobbyrussellBuilt-in
MinimalBuilt-in
LambdaBuilt-in
PowerblocksBuilt-in
AgnosterExternal (Rust)
SpaceshipExternal (Rust)
Powerlevel10kExternal (Rust)
StarshipExternal (Rust)
Powerline styles require a Nerd Font. Relay uses JetBrains Mono Nerd Font by default.

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>.json

On 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

ShellIntegrationHooks
zshZDOTDIR → ~/.config/relay/precmd / preexec
bash--rcfile ~/.config/relay/.bashrcPROMPT_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.

OSCPurpose
OSC 133;APrompt start
OSC 133;BCommand start (user typing)
OSC 133;COutput start (command submitted)
OSC 133;D;exitCommand finished with exit code
OSC 7Current working directory
OSC 1337iTerm2 compatibility (CurrentDir)
OSC 9999;askRelay 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

ProviderModels
OpenAIgpt-4o-mini, gpt-4, gpt-4o
Anthropicclaude-haiku-4-5, claude-sonnet, claude-opus

Slash Commands

CommandDescription
/helpShow help
/saveSave conversation
/clearClear history
/modelSwitch model
/copyCopy last response
/contextShow shell context
/runExecute command
/tokensShow token usage
/exitExit 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.

PatternColorExample
ErrorsRed (bold)error, fatal, exception
WarningsYellowwarning, deprecated
SuccessGreenOK, Done, PASSED, ✓
URLsBlue (underline)https://...
PathsCyan/usr/local/bin
IPv4Yellow192.168.1.1
Numbers + UnitsMagenta340ms, 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.

Visual Separators

Subtle gradient lines between commands make the terminal scannable at a glance.

Block Actions

Right-click in RECENT → Copy Output, Re-run, Scroll to Block, Add Favorite.

⌘⇧↑
Block Navigation

⌘⇧↑ / ⌘⇧↓ to jump between command blocks.

Inline Autocomplete

IDE-style dropdown that appears as you type, showing subcommands, flags, and descriptions.

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

Built-in completion specs for:

git docker npm cargo brew

Navigate with ↑/↓, accept with Tab, dismiss with Esc.

Inline Images

Display images directly in the terminal using the Kitty Graphics Protocol.

relay imgcat ~/Desktop/photo.png

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

SSH connections switch to a warning theme (e.g., Obsidian). Configurable per host pattern.

📁
Directory Rules

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.

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

Regex Triggers

Automatic actions when terminal output matches a pattern. Configure in Settings → Appearance → Regex Triggers.

🔔
Notifications

macOS notification when output matches (e.g., 'BUILD SUCCEEDED').

🔊
Sound

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.

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

When executed, a form appears for each placeholder. Live preview shows the resolved command before 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.

Auto-Detection

Detects git push from any shell (Relay, external terminal, IDE) via filesystem watching.

📊
Live Updates

Steps update every 5 seconds with animated progress bar and pulsing status dots.

📋
Job Logs

Click any step to expand its log inline below. Copy logs to clipboard with one click.

Settings → CI/CD Pipeline → GitHub Token

Inline Workflow

Inputs where the command happens. Snippets, pipeline logs, and blueprints expand right inside the sidebar — with live preview and a run button.

📝
Snippet inline form

Parameterized snippets expand with inline inputs. Live-resolved preview shows the final command. Run button is disabled while parameters are empty — no broken commands.

📋
Pipeline step log inline

Click a CI/CD step to expand its log directly below. Scrollable, selectable, with copy button.

📁
Blueprint folder picker

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.

Running

Yellow spinner ring (72% filled) rotates continuously. Linear, 1.2 seconds per turn.

Success

Full green ring with a checkmark in the center. Instantly recognizable in the step list.

Failed

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.

📂
Split inheritance

⌘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.

🧩
Blueprint inheritance

Blueprints inherit the first pane's path as the workspace root. Later splits inside a blueprint-launched workspace land there too.

🎯
Auto-fit layout

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).

🔀
Pane conversion

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.

🎨
Tree-sitter highlighting

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.

📑
Multi-tab + cursor memory

Multiple files open at once. Tab bar with dirty indicator. Cursor and scroll position survive per file across tab switches.

🗂️
File tree context menu

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.

Autocomplete

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.

🎭
6 editor themes

Relay Dark, Relay Light, Solarized Dark, Nord, Monokai, GitHub Light — all with authentic brand colors. Configurable in Settings → Code Editor → Theme.

Keyboard shortcuts

KeyAction
⌘SSave active file
⌘WClose active tab
⌘1⌘9Jump to tab N
⌘FOpen 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.

🔍
Repo scan via `git ls-files`

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.

📦
Supported stacks

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.

🏷️
Framework detection

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.

🧩
Monorepo-aware

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.

▶️
Clickable scripts

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.

Broadcast input

Type once — every selected pane gets the input in parallel. Perfect for multi-server operations, cluster maintenance, or comparative tests across containers.

📡
Enable

Toggle in the workspace sidebar — the BROADCAST section appears and lists every pane in the workspace with a checkbox.

Pane selection

Use checkboxes to pick which panes receive input. On enable all panes are pre-selected; deselect individual ones as needed.

🖥️
Typical use cases

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.

🔔
Visual + audible bell

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.

⏱️
Long-command notification

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.

🪝
Webhook notifications

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.

🌌
Aurora background

Animated mesh gradient with four colored blobs behind the window. 30 FPS via Canvas + drawingGroup() (GPU-accelerated). Color matches the active app theme.

📺
CRT effects

Retro themes get scanlines (Off/Light/Medium/Heavy configurable), a subtle edge vignette, and chromatic-aberration color fringes. Pure retro vibes, performance-neutral.

🔄
Auto-updates via Sparkle

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.

SettingDefaultDescription
colorSchemeEnabledfalseEnable auto appearance (Light/Dark/System)
colorSchemedarkMode: dark · light · auto (follows macOS)
appThemeIDrelay-darkApp theme (19 themes: 11 modern + 8 retro)
themeIDdark-defaultTerminal color palette (ANSI colors)
promptStyleIDrobbyrussellPrompt style (11 styles)
fontSize13Font size (8–32)
fontNameJetBrains Mono NerdFont family (Nerd Font recommended)
backgroundOpacity0.7Background opacity
semanticHighlightingtrueAuto-colorize errors, paths, URLs
cursorShapeblockblock · bar · underline
cursorBlinktrueCursor blinking on/off
cursorColorHex#4af09aCursor 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.

SettingDefaultDescription
shellPath$SHELLShell path (auto-detected)
shellLoginModetrueLogin shell (-l flag)
shellArgsAdditional shell arguments at launch
useUserZshrcfalseUse own .zshrc
optionAsMetafalseOption key as Meta
inheritSystemEnvtrueInherit system environment (default: enabled)
pathExtensionsPATH extensions (prepended to PATH)
autoLoadDotenvfalseAuto-load .env files in the working directory

Page 4: Notifications

Bell behavior, long-running command notifications, and webhook integration.

SettingDefaultDescription
audibleBellfalseSystem sound on terminal bell
visualBelltrueBrief flash on terminal bell
notifyLongCommandtrueNotify on commands > N seconds (background only)
webhookURLPOST request to custom URL on command finish

Page 5: Storage & Sessions

Project memory, session persistence, backup, and broadcast controls.

SettingDefaultDescription
projectMemoryEnabledtrueEnable project memory (per-directory context)
projectMemoryRetention30 TageRetention: 7 days · 30 days · Unlimited
saveTabsOnQuittrueSave tabs on quit
restoreWorkspacesOnLaunchtrueRestore 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.

SettingDefaultDescription
aiEnabledfalseEnable AI assistant (relay ask / relay explain)
aiProvideranthropicProvider: anthropic · openai
aiContextLines50Number 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