Relay Documentation

Installation

Relay is currently announced through the waitlist. Check the download page for availability; the following chapters describe the current app development build.

First Steps

After installation, you're ready in three steps.

Keyboard Shortcuts

Essential keyboard shortcuts for fast workflows.

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.

Glass Themes

Modern themes with glassmorphism, glow effects, and unique typography — a selection:

Retro Themes

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

Light/Dark Mode

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

Color Scheme

Configure the mode in Settings → Appearance → Color Scheme. In System mode, Relay observes the macOS appearance and switches themes instantly.

Pane Layouts

Eleven layout presets divide your workspace into up to four panes. Workbench adds a terminal dock below two work areas; Workbench 2 splits that dock into two terminals.

Prompt Styles

10 prompt styles in Relay-managed mode — Relay Compact, Robbyrussell, Minimal, Lambda, Powerblocks, Pure, Classic, Fish, Lean, Ops. In user-zshrc mode your own prompt (Powerlevel10k, Starship …) keeps running unchanged.

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.

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

OSC Sequences

Relay uses Operating System Command (OSC) sequences for communication between shell and app.

Shell Modes

Relay offers two modes for shell configuration.

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 asks for confirmation before switching: changing modes ends the current shell and starts a new one.
• Each pane keeps its own mode — independent of other panes and the global setting

Info Panel

⌘I switches between the narrow rail and the expanded info panel. Project groups environment and history, Library holds reusable collections, Global contains system tools and agents. AI opens workspace chat. Git lives in the left Git perspective; pipeline details in workspace status.

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 (planned)

Planned: Relay will detect active VPN tunnels (OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cisco AnyConnect and more providers) and show interface, IP, and provider in the Info Panel. Not yet shipped in the app.

AI Agent

Enable AI in Settings → AI and configure an API, a local server, or an installed agent CLI. relay ask answers in the terminal; ⌘⌥A opens the separate AI chat window with context from the active workspace.

Usage

In zsh/bash, relay ask keeps the Relay interface even with a CLI connection. relay agent explicitly opens the configured CLI’s original interface. relay status shows the active connection; relay resume opens Relay’s session picker.

Use -f to attach a file (repeatable), -k to continue the latest Relay conversation, -m to select a model, and -q for less formatting. Put -- before questions that start with a dash.

Connections and models

Supported connections include OpenAI, Anthropic, Google Gemini, and local OpenAI-compatible servers. Select a model in Settings from the list available for your connection. CLI mode requires the selected CLI to be installed and signed in.

MCP bridge — drive Relay from outside

Relay can open a local MCP server (Settings → Intelligence) that exposes the agent tools to external CLI agents like Claude Code or Codex CLI: create workspaces, split panes, switch layouts and themes, manage to-dos and notes. The socket is a local Unix socket (0600); the Python shim installs automatically.

Shell actions (run_command, write_file, git_push, write_to_terminal) ALWAYS require per-call approval in Relay — with a 120-second timeout. File-read and clipboard tools are never reachable over MCP.

DevTools in the browser pane

Every browser tab can attach a DevTools pane — with eight tabs:

Console with eval, live autocomplete, and $0/$1/$_; Network with request bodies, type filters, waterfall, throttle, HAR export, and replay (copy as fetch/cURL); Elements with a live DOM tree, toggleable CSS rules, and editable attributes. ⌥⌘I additionally opens Safari's own Web Inspector.

SSH & SFTP

Relay reads ~/.ssh/config (including ProxyJump), shows saved hosts with live latency (every 15 seconds) in the sidebar, and manages tunnels. If a connection drops, a reconnect banner appears instead of a dead session.

The SFTP browser shows local and remote files side by side: browse, rename, delete, upload, and download. The separate editor mode downloads the remote directory into a local cache on demand and uploads edits back.

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
• Click to open the inline command explanation. Alternatively, use relay explain in the terminal.
• Requires a configured AI connection in Settings.

Semantic Colorizer

Relay automatically colorizes terminal output: errors, warnings, URLs, paths, and numbers get context-aware colors — without overwriting existing ANSI output.

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.

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.

Clickable Paths & URLs

File links in terminal output open in Relay’s editor; web URLs open through macOS. Relay recognizes OSC 8 links as well as paths and URLs in ordinary output, including already colored text.

Regex Triggers

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

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.

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 via a click on the pane name pill. 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. The workspace status opens pipeline details with jobs and steps.

Docker containers

The Docker section under Global lists local containers with image, status and mapped ports.

Each container offers start, stop, and restart buttons. Clicking the log icon streams the container's logs live into the active terminal; clicking a mapped port opens the service in the browser pane.

Relay detects when Docker isn't installed or the daemon is stopped and shows a clear hint instead of an empty list. It only refreshes while the section is visible — no background load.

AI usage dashboard

Relay shows provider-reported quotas and reset times. Codex supplies them through its CLI account interface; Claude through captured limit events from runs started by Relay.

These are not cost estimates derived from token prices. A manual Claude refresh makes a small model request and counts towards quota. Unavailable or stale data is labelled accordingly.

Browser downloads

The browser pane supports user-initiated downloads: download links land in a download manager with its own info-panel section, and PDFs open right in the built-in viewer.

Device emulation

Responsive design mode renders the page in the browser pane inside iPhone and iPad frames — including Dynamic Island and home indicator. Test responsive layouts without leaving Relay.

Sidebar Cockpit

Workspaces live in the titlebar; pane topology and layout selection sit in the info panel on the right (⌘I). No modal, no popover — everything stays in view.

Inline Workflow

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

Pipeline Step Rings

CI/CD steps render as animated progress rings — no more linear bars. Status legible at a glance.

Workspace directory inheritance

When you open a workspace at a specific path, every new split lands in the same project — not the home directory.

CardSections & components

Your project on the left. Its context on the right. Room to work in between. Explore the cards, components and tools in detail.

Browser

⌘3 opens the active pane’s browser slot. Multiple tabs, bookmarks, history, and a configurable search engine are built in. Cookies and website data are isolated per workspace; private mode uses a non-persistent data store.

Open your local dev server in a browser pane beside the editor. Automatic reload on save is configurable per workspace. Use the Inspector button to open DevTools for the current browser tab.

Screenshots capture the viewport or full page, save to Downloads, and copy to the clipboard. They also appear under Global → Browser Shots. ⌘+/⌘− change page zoom; ⌘0 resets both zoom and trackpad magnification.

Git and changes

The left Git perspective shows branches, changes and staging. Click a file to open its diff. Commit, push and pull operate on the workspace project root.

Git actions use the workspace’s project folder. Browsing a different folder in the Explorer does not change that project folder. If an operation fails, Relay shows the actual Git output.

Notes & to-dos

Notes and to-dos each have their own icon on the left. ⌘⇧N opens the planning window at notes; ⌘⇧T opens it at tasks. In list view, a note opens beside the list. Narrow windows offer a Notes button to return to the list. Use the pencil and preview controls to edit Markdown or read its formatted output.

The plus button in each sidebar section opens an inline input. Both views keep their own search. Completing a task briefly shows a green checkmark and strikethrough before hiding it. Show completed to-dos to review, reopen or bulk-delete them after confirmation. Search and filters limit which tasks are deleted.

Clipboard Note Capture is optional. Under Notes & Todos, choose whether copied text and images become notes only from Relay or system-wide.

Agent dashboard

The Agents card in Global shows detected runs, active agents and waiting sessions. Expand individual cards to inspect their details.

Read the captured task, latest activity and changed files. Respond to supported approvals and text prompts in the card, or jump to the linked session.

Start a new agent opens a terminal tab for a configured CLI. The active workspace needs a terminal pane. Sign-in and available features depend on your setup.

Code Editor

Every pane carries terminal, editor & co. as slots — ⌘2 switches the active pane to the editor, ⌘1 back to the terminal, state preserved. File tree on the left, tabbed editor on the right. Powered by CodeEditSourceEditor (tree-sitter).

Code intelligence and file previews

In Settings → Editor, the Language-Server Doctor checks available servers and offers installation help. ⌘-click jumps to a definition and ⌘⇧E finds references. Hover shows documentation or diagnostics; error and warning counts open the diagnostics list. Without a server, Relay uses text-based fallbacks.

⌘F opens Find & Replace; ⌘⇧F searches the project. The editor also displays images, PDFs, SVG, CSV/TSV, and Markdown, plus read-only Office previews. Git gutter markers show local changes; file history opens earlier revisions read-only.

Keyboard shortcuts

Stack Detector

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.

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.

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

VPN detection (planned)

Planned feature: Relay will scan all `utun*` interfaces on macOS and identify the active VPN provider via the process list. The VPN section would only appear in the sidebar when a tunnel is actually up — no visual noise when nothing's running. This feature is not yet shipped in the current app.

Planned provider detection

Planned: OpenVPN, WireGuard, Tailscale, NordVPN, Mullvad, Cloudflare WARP, Cisco AnyConnect, ExpressVPN, ProtonVPN, Surfshark, PIA, Windscribe, Hotspot Shield, ZeroTier — each identified by its process name. Not yet shipped in the app.

Polish & atmosphere

Small details that make the difference — from notifications for long-running commands to the animated background.

Settings

Open Settings with ⌘,. Pages are arranged in six groups. The overview below uses the interface’s page names; use search to find individual options.