Relay

Python OpenRouter OpenAI SDK Model Context Protocol Pydantic
Rich prompt_toolkit Click DuckDuckGo Docker

Relay is an open-source AI coding agent that runs in your terminal. It connects to LLMs through OpenRouter, reads and edits your code with a built-in tool set, runs shell commands, and streams everything through a full-screen TUI.

Relay planning and executing a multi-step task in the terminal

[!WARNING] Work in progress. The agent loop, tool calling, terminal UI, and approval flow work end to end. The approval policy is set in config (approval = "on_request" by default) — there is no way to switch it mid-session yet. Sub-agents still auto-approve their own tool calls, so use Relay in a directory you don't mind it touching.

Functionality

Interface
Interactive TUI Full-screen terminal interface built on Textual, with streaming responses, live tool call output, and token usage tracking.
Single-shot mode Pass a prompt as an argument for non-interactive runs, suitable for scripting.

Tools
Files read, write, edit, grep, glob, and list_directories for working with a codebase.
Shell The shell tool executes commands in the working directory.
Planning A plan tool tracks steps (a todo list) across the agent loop.
Network Web search via DuckDuckGo and URL fetching.
Memory Key-value storage that survives across sessions.
MCP Connects to external MCP servers for additional tools and data sources.

Agent
Sub-agents Specialized agents the main agent can delegate to: codebase_investigator, code_reviewer, software_architect, test_writer, debugger.
AGENTS.md Project instructions are picked up automatically and followed while working.
Context pruning Old tool outputs are cleared once they pile up past the recent working set, reclaiming tokens without touching the conversation itself.
Compaction When the context window fills up, history is summarized into a continuation brief and the session resumes from it instead of erroring out.
OpenRouter backend Authenticate once with relay login (browser OAuth) or paste an API key. Model, temperature, and context window are configurable in ~/.config/relay/config.toml, with per-project overrides in .relay/config.toml.

Getting started

# 1. Install Relay
pip install relay-code

# 2. Log in (opens your browser to authorize with OpenRouter)
relay login
relay login --paste   # or paste an API key directly

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

# Remove the saved API key
relay logout

Project instructions (AGENTS.md)

Drop an AGENTS.md at the root of your repo and Relay loads it as developer instructions at startup, use it for build and test commands, code style, or anything else the agent should know before touching your code

Relay walks up from the working directory to the repository root, so running relay inside a subdirectory still picks up the root file. Every AGENTS.md found along the way is included, ordered outermost first.

# AGENTS.md

## Commands
- Test: `pytest`
- Lint: `ruff check .`

## Style
- Type hints on all public functions.

The scope of an AGENTS.md file is the directory tree it sits in, and the more deeply nested file wins on conflicts. Files below the working directory are read on demand as the agent works in those subdirectories. Instructions you give directly in a prompt always take precedence over AGENTS.md.

Roadmap

Currently being worked on:

  • Slash commands: in-session commands (e.g. /approval to switch approval mode) instead of only config-file settings.
  • Approval flow: prompting before file edits and shell commands is in place; still to come is switching the mode mid-session and extending confirmations to sub-agents.
  • Session management: saving, resuming, and switching between sessions.

License

GNU GENERAL PUBLIC LICENSE v3.0

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for andrefetch from gravatar.com andrefetch

Credits

Author: andrefetch

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.11

Tags

ai agent cli coding-assistant tui openrouter

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

relay_code-0.0.22.tar.gz (75.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

relay_code-0.0.22-py3-none-any.whl (90.1 kB view details)

Uploaded Python 3

File details

Details for the file relay_code-0.0.22.tar.gz.

File metadata

  • Download URL: relay_code-0.0.22.tar.gz
  • Upload date:
  • Size: 75.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for relay_code-0.0.22.tar.gz
Algorithm Hash digest
SHA256 f85d69a596e1cf056222a436b685e93e0debdd8f6165bd4bf77bb720bed08379
MD5 9d6cd848f90a38723ee01b88d4764ff7
BLAKE2b-256 1ab0d287687095b381efef7abef1ddbf90614302f8fcc4e600fa9c859425ffe5

See more details on using hashes here.

Provenance

The following attestation bundles were made for relay_code-0.0.22.tar.gz:

Publisher: python-publish.yml on andrefetch/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file relay_code-0.0.22-py3-none-any.whl.

File metadata

  • Download URL: relay_code-0.0.22-py3-none-any.whl
  • Upload date:
  • Size: 90.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for relay_code-0.0.22-py3-none-any.whl
Algorithm Hash digest
SHA256 dbb64201d3936ce240cb33873bd1d7c52e7ee55184e2d4b6e6c73be385b07683
MD5 40744238029d583a7e6e5c8a28cba269
BLAKE2b-256 f7359f64cefe2003bd776fa7f0bad7b564847f935aa794bc45727b2aea78b3c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for relay_code-0.0.22-py3-none-any.whl:

Publisher: python-publish.yml on andrefetch/relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page