Relay

An open-source, terminal-based AI coding agent that reads your code, calls tools, and helps you build.

Get Started Source Code

relay
Demo of Relay running in the terminal

Features

Interactive TUI

Full-screen terminal interface with streaming responses and real-time tool calls.

Single-Shot Mode

Pass a prompt directly for quick, non-interactive runs.

Built-in Tool Set

Read, write, edit, grep, glob, and run shell commands. Includes a todo plan tool.

Web Search & Fetch

Search the web via DuckDuckGo and fetch URL content.

Persistent Memory

Store and retrieve key-value memories across sessions.

MCP Support

Connect to MCP servers for custom tools and data sources.

Sub-Agents

Specialized agents for codebase investigation, code review, architecture, testing, and debugging.

Approval Flow

Six approval modes, from strict read-only to full autonomy.

Session Management

Save sessions, create checkpoints, and resume right where you left off.

OpenRouter

Built on OpenRouter. Authenticate once with relay login.

Approval Modes

Every mutating tool call passes through the approval flow first. The mode decides how much Relay asks about, from strictest to most permissive.

read-only

Safe

Rejects anything that is not known safe.

ask

Default Safe

Confirms every mutating tool call.

auto-edit

Safe

Edits freely, confirms shell commands.

on fail

Caution

Runs freely and only asks after a failure.

auto

Caution

Runs everything except dangerous commands.

yolo

Dangerous

Approves everything, including dangerous commands.

Set it with approval in .relay/config.toml, or switch mid-session with /approval <mode>.

Getting Started

  1. Install Relay 
    pip install relay-code
  2. Log in

    Authorize with OpenRouter in your browser (or paste an API key manually).

    relay login

    Use relay login --paste to enter an API key directly.

  3. Run it 
    relay                 # interactive mode
    relay "your prompt"   # single-shot mode
    relay --cwd /path     # run against a different directory

Usage

Interactive TUI

Launch the full-screen terminal UI for an interactive session.

relay

Single-Shot Mode

Run a single prompt without the interactive interface.

relay "Refactor the auth module"

Custom Working Directory

Point Relay at a different directory than your current one.

relay --cwd /path/to/project

Account Management

Log out to remove your saved API key.

relay logout

Tooling Architecture

Core

  • read: Read file contents with line numbers
  • write: Create or overwrite files
  • edit: Surgical text replacement
  • grep: Regex search across files
  • glob: Find files by pattern
  • shell: Execute shell commands
  • list_directories: List directory contents
  • plan: Todo list for task tracking

Sub-Agents

  • codebase_investigator: Explore code structure
  • code_reviewer: Review code for bugs and quality
  • software_architect: Write and maintain clean code
  • test_writer: Write tests for edge cases
  • debugger: Find and fix bugs

Network

  • search: Web search via DuckDuckGo
  • fetch: Fetch URL content

Memory

  • memory: Store and retrieve persistent key-value data

MCP

  • Connect to external MCP servers for custom tools and data

Commands

Slash Commands

  • /help: Show help
  • /exit or /quit: Exit the agent
  • /clear: Clear conversation history
  • /config: Show current configuration
  • /model <name>: Change the model
  • /approval <mode>: Change approval mode
  • /stats: Show session statistics
  • /tools: List available tools
  • /mcp: Show MCP server status

Session Management

  • /save: Save the current session
  • /checkpoint [name]: Create a checkpoint
  • /checkpoints: List available checkpoints
  • /restore <checkpoint_id>: Restore a checkpoint
  • /sessions: List saved sessions
  • /resume <session_id>: Resume a saved session

License

Relay is licensed under the GNU General Public License v3.0.

View the project on GitHub or install it from PyPI.