relay-agent 0.1.0

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.

Relay

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

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 · Repo: GitHub · Issues: file one

---

What is Relay?

Relay is the autonomous cousin of 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	Alpha, live on PyPI

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)

# 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:

# .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):

# 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)

# .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)

# 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)

# 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 (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 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.

About

Relay is built and maintained by ThinkNext Software, 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.

If Relay (or Cascade) is helpful to your team, consider working with us on your next project.

Follow along: @ThinkNextHQ · LinkedIn · Blog