Documentation

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 14 Sonoma+, Universal Binary (Apple Silicon & Intel)

First Steps

After installation, you're ready in three steps.

Choose a theme

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

Set your prompt style

Choose one of 12 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
`⌘T`	New pane
`⌘W`	Close pane
`⌘D`	Split horizontal
`⌘⇧D`	Split vertical
`⌘⌥]`	Focus next pane
`⌘⌥[`	Focus previous pane
`⌘+`	Increase font size
`⌘−`	Decrease font size
`⌘0`	Reset font size (13)
`⌘I`	Toggle info panel
`⌘\`	Toggle icon rail
`⌘P`	Command palette

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

Ten historical terminals (1971–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

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

Six 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
`1+2`	3	One large pane left, two small on the right
`2×2`	4	Four panes in a 2×2 grid
`Focus`	2	One focused pane, one dimmed secondary pane

Layouts auto-adjust: adding a pane upgrades the layout, removing one downgrades it.

Prompt Styles

11 built-in prompt styles — selectable in Settings, applied live instantly. No .zshrc editing needed.

Style	Origin	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	External (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

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.

│

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 view its logs in a popover. Copy logs to clipboard with one click.

Settings → CI/CD Pipeline → GitHub Token

Settings

Relay organizes 40+ settings into 7 pages. All settings are stored in UserDefaults and take effect immediately. Groups: General (Appearance, Keyboard) · Terminal (Shell & Environment, Notifications) · Advanced (Storage & Sessions, Shell Integration, AI Assistant).

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 (17 themes: 7 glass + 10 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

Relay Documentation

Installation

Direct Download

Homebrew

First Steps

Choose a theme

Set your prompt style

Set up workspaces

Keyboard Shortcuts

Theme System

Three-Layer Architecture

AppTheme

TerminalTheme

PromptStyle

Glass Themes

Retro Themes

Design Tokens

Light/Dark Mode

Color Scheme

Pane Layouts

Prompt Styles

Workspaces

Project Memory

Storage

Shell Integration

Supported Shells

OSC Sequences

Shell Modes

Relay Prompt

User .zshrc

Per-Pane Shell Mode

Info Panel

Project Memory

Recent Commands

Favorites

Working Directories

Open Ports

VPN Detection

AI Agent

Usage

Providers

Slash Commands

Automatic Error Explain

Semantic Colorizer

Command Blocks

Inline Autocomplete

Inline Images

Automatic Profile Switching

Clickable Paths & URLs

Regex Triggers

Parameterized Snippets

Sticky Command Header

Session Blueprints

Pane Coloring

CI/CD Pipeline Monitor

Settings

Page 1: Appearance

Page 2: Keyboard

Page 3: Shell & Environment

Page 4: Notifications

Page 5: Storage & Sessions

Page 6: Shell Integration

Page 7: AI Assistant

Relay-specific Variables