Metadata-Version: 2.4
Name: relay-agent
Version: 0.1.0
Summary: Open-source autonomous AI agent: label an issue, get a tested pull request. Runs in your CI (GitHub Actions, GitLab CI, Bitbucket Pipelines, or Azure Pipelines). Standalone: no inter-package dependencies.
Project-URL: Homepage, https://thinknextsoftware.com
Project-URL: Documentation, https://github.com/Thinknext-Software-Solutions/Relay
Project-URL: Repository, https://github.com/Thinknext-Software-Solutions/Relay
Project-URL: Issues, https://github.com/Thinknext-Software-Solutions/Relay/issues
Project-URL: Changelog, https://github.com/Thinknext-Software-Solutions/Relay/releases
Author-email: ThinkNext Software Solutions <hello@thinknextsoftware.com>
License: MIT License
        
        Copyright (c) 2026 ThinkNext Software Solutions
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,agentic-ai,ai,ai-agent,anthropic,automation,autonomous,azure-pipelines,bitbucket-pipelines,ci-cd,claude,code-generation,gemini,github-actions,gitlab-ci,llm,merge-request,ollama,open-source,openai,pull-request,sdlc,self-hosted
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pygithub>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: claude-agent-sdk>=0.1; extra == 'all'
Requires-Dist: google-generativeai>=0.7; extra == 'all'
Requires-Dist: openai>=1.30; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: claude-code
Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-code'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.7; extra == 'google'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Description-Content-Type: text/markdown

# Relay

> Label an issue, get a tested pull request. Autonomously, in your own CI, on whatever VCS you already use.

[![PyPI](https://img.shields.io/pypi/v/relay-agent.svg?label=PyPI&color=22d3ee)](https://pypi.org/project/relay-agent/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Status](https://img.shields.io/badge/status-alpha-22d3ee.svg)](#roadmap)
[![Built by ThinkNext](https://img.shields.io/badge/built%20by-ThinkNext-22d3ee.svg)](https://thinknextsoftware.com)

> **Status**: alpha, live on PyPI as `relay-agent==0.1.0a1`. The local CLI works end-to-end (`relay init`, `relay run owner/repo#42`). The GitHub Actions wrapper lands in 0.1.0a2. Multi-CI (GitLab CI, Bitbucket Pipelines, Azure Pipelines) lands in v0.2 and v0.3.
>
> **Install**: `pip install relay-agent` &middot; **Repo**: [GitHub](https://github.com/Thinknext-Software-Solutions/Relay) &middot; **Issues**: [file one](https://github.com/Thinknext-Software-Solutions/Relay/issues)

---

## What is Relay?

Relay is the **autonomous** cousin of [Cascade](https://github.com/Thinknext-Software-Solutions/Cascade). Where Cascade has humans in the loop at every gate (story review, PR review), Relay runs hands-off from a label on an issue to a tested PR waiting for review.

Drop a single workflow file in your repo. Label any issue with `relay`. The agent:

1. Reads the issue and understands what is being asked
2. Plans the code changes
3. Implements them on a new branch
4. Writes and runs tests
5. Opens a PR for human review

All running in **your** CI, using **your** LLM API key, with code that **never leaves your org**.

## Why Relay sits next to Cascade, not on top of it

Different problem, same author. The two are complementary:

| | Cascade | Relay |
|---|---|---|
| **Entry point** | Meeting recording, tracker ticket, or one-line prompt | Labeled issue |
| **Where it runs** | Your laptop or CI on demand | Your CI, triggered by the label |
| **Human gates** | Story review BEFORE code, PR review BEFORE merge | PR review BEFORE merge |
| **Best for** | Translating fuzzy requirements into code with deliberation | Backlog clearing, well-scoped tickets, autonomy |
| **Status** | Alpha, [live on PyPI](https://pypi.org/project/cascade-agent/) | Alpha, [live on PyPI](https://pypi.org/project/relay-agent/) |

Pick Cascade when you want to think about the work before code gets written. Pick Relay when the work is well-defined and you want it ticked off without context-switching.

## Supported (planned)

Cascade's multi-provider stance, applied to autonomous CI workflows. v0.1 ships GitHub Actions; the rest land in v0.2 and v0.3.

| CI runtime | Triggered by | Opens | v0.1 | v0.2 | v0.3 |
|---|---|---|---|---|---|
| **GitHub Actions** | `relay` label on a GitHub issue | GitHub PR | ✅ | | |
| **GitLab CI** | `relay` label on a GitLab issue | GitLab MR | | ✅ | |
| **Bitbucket Pipelines** | `relay` label on a Bitbucket issue | Bitbucket PR | | ✅ | |
| **Azure Pipelines** | `relay` tag on an Azure Boards work item | Azure DevOps PR | | | ✅ |

LLM providers will mirror Cascade's matrix: Anthropic, OpenAI, Google Gemini, Claude Code, Ollama. Provider choice is one config line.

Languages will mirror Cascade's eight built-in profiles: Python, TypeScript, JavaScript, Go, Rust, Java, Ruby, C#. Adding a ninth is one registry entry, same pattern as Cascade.

## Intended developer experience

The local CLI (`relay run owner/repo#42`) is functional today in `0.1.0`. The GitHub Actions wrapper below is the v0.1.1 shape and lands shortly after.

### Install (standalone)

```bash
# Core install + the LLM provider you want:
pip install 'relay-agent[anthropic]'        # Anthropic Claude
pip install 'relay-agent[openai]'           # OpenAI
pip install 'relay-agent[google]'           # Google Gemini
pip install 'relay-agent[claude-code]'      # Local Claude Code subscription, no API key
pip install 'relay-agent[all]'              # All providers

# Configure credentials (stored at ~/.config/relay/config.yaml):
relay configure llm anthropic --key sk-ant-xxx --set-default
relay configure vcs github --token ghp_xxx --set-default
```

### GitHub (v0.1)

Add a single workflow file to your repo:

```yaml
# .github/workflows/relay.yml
name: Relay
on:
  issues:
    types: [labeled]

jobs:
  relay:
    if: github.event.label.name == 'relay'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: thinknext/relay@v0
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```

Add a config file (optional; sensible defaults provided):

```yaml
# relay.yaml
version: 1

agent:
  provider: anthropic       # anthropic | openai | google | claude_code | ollama
  model: claude-opus-4-7
  max_iterations: 1

allowed_paths:
  - src/**
  - tests/**
  - docs/**

disallowed_paths:
  - .github/**
  - migrations/**

test_command: pytest
```

That is it. Label any issue with `relay` and watch it work.

### GitLab (v0.2)

```yaml
# .gitlab-ci.yml
relay:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "trigger" && $RELAY_ISSUE_IID'
  script:
    - pip install relay-agent
    - relay run --issue $RELAY_ISSUE_IID
```

With a webhook on the GitLab project that fires when an issue gets the `relay` label.

### Bitbucket Pipelines (v0.2)

```yaml
# bitbucket-pipelines.yml
custom:
  relay:
    - step:
        script:
          - pip install relay-agent
          - relay run --issue $RELAY_ISSUE_ID
```

With a Bitbucket webhook triggering the custom pipeline on the `relay` label.

### Azure Pipelines (v0.3)

```yaml
# azure-pipelines.yml
trigger: none
pr: none

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: pip install relay-agent
- script: relay run --work-item $(Build.SourceBranch)
  env:
    ANTHROPIC_API_KEY: $(ANTHROPIC_API_KEY)
```

Triggered by a service hook from Azure Boards when a work item is tagged `relay`.

## How it works (every backend)

```
                  YOUR ISSUE TRACKER                     YOUR CI                    YOUR VCS
                  ==================                     =======                    ========

  Label "relay" added  ───►  webhook fires  ───►  Relay agent runs:        ───►   PR / MR opened
  (GitHub Issues /                                 plan → code → test →             on a new branch
   GitLab Issues /                                 self-review                       awaiting human
   Bitbucket Issues /                                                                review
   Azure Boards)
                                                  (Python, runs in YOUR
                                                   GitHub Actions /
                                                   GitLab CI /
                                                   Bitbucket Pipelines /
                                                   Azure Pipelines runner)
```

### Five sub-agents, sequential, focused

| Agent | Job | Output |
|---|---|---|
| **Planner** | Read issue + repo, decide what files to touch and how | File list + plan summary |
| **Coder** | Implement the plan | Diffs |
| **Tester** | Add tests, run full suite | Pass/fail + new test files |
| **Reviewer** | Self-critique the diff | Issue list or "looks good" |
| **PR Opener** | Compose PR title/body, push branch, open PR or MR | PR/MR URL |

Each is a focused LLM call with a focused prompt. We deliberately *don't* use heavy agent frameworks in v0.1, so the code stays small and hackable.

## Security model

Security is the differentiator, so it is also the bar to clear. Relay's design boundaries:

- ✅ Only triggered by a label you control on issues your team already owns
- ✅ Code generation happens in YOUR CI runner. Not on a third-party SaaS, not on a ThinkNext server
- ✅ Uses YOUR LLM API key. Multi-provider; pick whichever your team is authorized for
- ✅ Source code never leaves your org's network, except to the LLM provider you explicitly configured
- ✅ All file changes live on a new branch, never on default
- ✅ **Relay never merges**. Every change requires human approval
- ✅ Sandboxed to allowed paths in `relay.yaml`
- ✅ Cannot modify CI/CD configs or `.github/` / `.gitlab-ci.yml` / equivalent
- ✅ Cannot modify its own config file (`relay.yaml`)
- ✅ Only runs `pytest` (or the configured test command) and `git` commands. No arbitrary shell access

Want a deeper dive? See [docs/security.md](docs/security.md) (lands with v0.1).

## Comparison vs alternatives

| | Cursor | Aider | Devin | Sweep | **Relay** | **Cascade** |
|---|---|---|---|---|---|---|
| Autonomous (issue → PR) | ❌ | ❌ | ✅ | ✅ | ✅ | partial (review gate) |
| Open source | ❌ | ✅ | ❌ | partial | ✅ | ✅ |
| Self-hosted (your infra) | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Source never leaves your org | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Multi-VCS (GitHub, GitLab, Bitbucket, Azure) | ❌ | partial | ❌ | GitHub only | ✅ (planned) | ✅ |
| Multi-LLM provider | partial | ✅ | ❌ | ❌ | ✅ (planned) | ✅ |
| Bring your own LLM key | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
| Free for individuals | partial | ✅ | ❌ | partial | ✅ | ✅ |

## Roadmap

| Version | Status | Highlights |
|---|---|---|
| **v0.1.0a1** | Shipped 2026-05-26 | Local CLI: `relay init`, `relay run`, `relay version`. Issue fetching, plan/code/test/self-review/PR pipeline. All 5 LLM providers via cascade-agent shim (Anthropic, OpenAI, Google, Claude Code, Ollama). All 8 language profiles. Sandboxing via `relay.yaml`. 56 tests passing. |
| **v0.1.0** | **Shipped (2026-05-26)** | Standalone release: zero runtime dependency on cascade-agent. Vendored LLM client, languages, planner, coder, repo, tester, and user-config modules. New `relay configure llm/vcs/show` commands at `~/.config/relay/config.yaml`. Per-provider install extras: `relay-agent[anthropic]`, `[openai]`, `[google]`, `[claude-code]`, `[all]`. 56 tests passing. |
| v0.1.0a2 | Target 2026-07-19 | GitHub Actions wrapper (`.github/workflows/relay.yml`) so the agent runs in CI automatically when an issue is labeled. Real-world dogfooding feedback rolled in. |
| v0.2 | Planned Q4 2026 | GitLab CI + Bitbucket Pipelines runtimes. Cost monitoring + `--max-cost` budget caps. Multi-issue batch mode. |
| v0.3 | Planned Q1 2027 | Azure Pipelines runtime, multi-repo coordination, PR-comment iteration loop (Relay reads review comments and ships a follow-up commit), Slack/Teams notifications. |
| v1.0 | Planned mid-2027 | Stable API, full provider/language parity with Cascade, hosted-runner option for teams without their own CI. |

Roadmap is directional. We will adjust based on real user feedback once people start trying v0.1.

## FAQ

**Q: How is this different from Cascade?**
A: Cascade is interactive. You feed it a meeting / ticket / prompt; you review the extracted stories; you review the resulting PR. Relay is autonomous: you label an issue, you review the PR. Same agent loop underneath; different human-in-the-loop posture. Pick whichever matches the work.

**Q: Why not just use Devin?**
A: Devin is closed-source and SaaS-only. Many companies cannot send code to a third party. Relay solves that.

**Q: Why not use Cursor with macros?**
A: Cursor is great for active development. Relay is for autonomous backlog clearing, a different use case. They are complementary, not competitive.

**Q: How much will it cost to run?**
A: You pay your own LLM costs. Rough estimate on Claude Opus: a small bug fix costs $0.50-$2; a larger feature: $5-$15. Highly variable by task complexity. Configurable `--max-cost` will cap it.

**Q: What if Relay produces bad code?**
A: It opens a PR for human review. You merge or reject. Relay never merges. Bad PRs can be closed with no harm done.

**Q: Can I use this on a private repo?**
A: Yes, that is the primary use case. Relay runs in your own CI, so private repos work fine.

**Q: Does it work with monorepos?**
A: v0.1 supports single-repo. Multi-repo / monorepo-aware features are v0.3.

**Q: Will there be a hosted version?**
A: Not from us in the foreseeable future. We are committed to OSS + self-hosted. If you want hosted, fork it.

**Q: When can I actually try this?**
A: v0.1 targets 2026-07-19. Star + watch this repo to be notified.

## Contributing

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

Quick version:
- Issues and PRs welcome
- Discuss in GitHub Discussions for non-trivial changes before opening PRs
- Code style: Black + Ruff for Python
- Tests required for new features

## License

MIT. See [LICENSE](LICENSE).

## About

Relay is built and maintained by [ThinkNext Software](https://thinknextsoftware.com), an AI-augmented engineering and staffing firm. We use AI at every step of the SDLC and ship the tools we use ourselves. Relay is the autonomous-CI counterpart to our flagship [Cascade](https://cascadeagent.dev).

If Relay (or Cascade) is helpful to your team, consider [working with us](https://thinknextsoftware.com#contact) on your next project.

Follow along: [@ThinkNextHQ](https://twitter.com/ThinkNextHQ) · [LinkedIn](https://linkedin.com/company/thinknextsoftware) · [Blog](https://thinknextsoftware.com/blog/)
