Relay

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, and terminal UI work end to end, but there is no approval flow yet. The interactive TUI auto-approves every tool, so Relay can change files and run commands without asking. Use it in a directory you don't mind it touching.

What it does

  • 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.
  • File tools: read, write, edit, grep, glob, and list_directories for working with a codebase.
  • Shell access: the shell tool executes commands in the working directory.
  • Task planning: a plan tool maintains a todo list across the agent loop.
  • Network tools: web search via DuckDuckGo and URL fetching.
  • Persistent memory: key-value storage that survives across sessions.
  • MCP support: connects to external MCP servers for additional tools and data sources.
  • Sub-agents: specialized agents (codebase_investigator, code_reviewer, software_architect, test_writer, debugger) that the main agent can delegate to.
  • 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

Roadmap

Currently being worked on:

  • Approval flow: prompting before file edits and shell commands instead of auto-approving every tool call.
  • Context pruning and compaction: trimming and summarizing conversation history to stay within the context window on long sessions.
  • 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:
Newer release available (0.0.22)

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.21.tar.gz (64.6 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.21-py3-none-any.whl (78.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: relay_code-0.0.21.tar.gz
  • Upload date:
  • Size: 64.6 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.21.tar.gz
Algorithm Hash digest
SHA256 b949ea3a6c1b4b3313a2c212bcc87181dd6fef806915bdde6b7314847880761c
MD5 b5f3c3bba2eae9d60c124b7aafd3b148
BLAKE2b-256 81a900cf0408d1ed35de18adfc3058c692cbc7d1d7cfe2d27ab3414911affbdc

See more details on using hashes here.

Provenance

The following attestation bundles were made for relay_code-0.0.21.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.21-py3-none-any.whl.

File metadata

  • Download URL: relay_code-0.0.21-py3-none-any.whl
  • Upload date:
  • Size: 78.6 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.21-py3-none-any.whl
Algorithm Hash digest
SHA256 e69a56070cfb278333edfa4b50bba87704259d8420df3645c8e1e74cac7e973b
MD5 0a7a3f04f944aa20b95c8e7350a9cceb
BLAKE2b-256 40ae83a1cc82774b9e8e0eff03c52c3b5c59fac807e2f8a193e2f816570ef4aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for relay_code-0.0.21-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