Issue-driven orchestration for real engineering work

Let Ralph code while you sleep.

Ralph turns GitHub Issues into planned, validated, and reviewable Pull Requests. It is built for larger tasks, stricter execution, and auditable repo-first delivery instead of brittle one-shot prompting.

Star on GitHub See Quick Start

Plan-firstBreak large work into runnable subtasks
Validator-gatedCompletion depends on validation, not “code generated”
Chat-to-repoFeishu triggers, GitHub stays the source of truth

GitHub Issue / Feishu command

Ralph plans the task

Ralph executes one runnable subtask

Ralph validates the result

Ralph updates the same draft PR

Validation passes → issue closes

Issue → PR A stricter engineering loop instead of a long prompt run

Single runnable subtask Each workflow run advances one concrete step

GitHub as source of truth Issues and PRs remain auditable at every stage

Why Ralph

Built for bigger tasks than a single friendly LLM loop can reliably handle

Ralph uses a stricter execution model: plan first, execute one runnable subtask per run, persist state, keep the same PR alive, and only declare success when validation passes.

Validator-first completion

A branch with commits is not success. Ralph gates completion on explicit validation output.

Incremental orchestration

Large tasks become runnable slices, reducing the chance of a brittle all-at-once rewrite.

Draft PR first

Work becomes visible early without pretending the task is done.

Cross-repo ready

A central Ralph deployment can dispatch to another target repo and keep routing attached.

Feishu ingress

Create, approve, reject, and track tasks from chat while GitHub remains the execution truth.

Stateful by design

Subtasks and execution snapshots persist across workflow runs, not just inside logs.

Workflow

A practical loop for issue-driven automation

Create an issue or send a Feishu command

Describe the goal, requirements, constraints, and acceptance criteria.

Generate an execution plan

Ralph decomposes larger work into subtasks and can pause for approval.

Execute one runnable subtask

Each run makes one defensible change instead of trying to finish the whole project at once.

Validate, update PR, continue

The same draft PR evolves until validation passes and the issue is ready to close.

User / Team

GitHub Issue / Feishu

GitHub Actions

Planner → Execution → Validator → PR

Comparison

What changes when you stop treating generated code as finished work

Approach

Typical limitation

Ralph stance

Single long-prompt coding agent

Loses structure on larger tasks

Plan first, then execute one runnable subtask at a time

Trigger-only issue bot

Starts work but lacks persistent task memory

Persists subtasks and execution state across runs

Chat-first coding workflow

Can drift away from audited repo state

GitHub issue and PR remain the source of truth

Ungated code generation

“Generated” gets mistaken for “done”

Completion is gated by explicit validation

Quick Start

Get Ralph running without building another platform around it

1. Install into your repo

git clone https://github.com/YOUR_GITHUB_USER/ralph.git /tmp/ralph
cd YOUR_PROJECT
/tmp/ralph/scripts/setup.sh

2. Add credentials

Secrets:
RALPH_API_KEY
RALPH_GITHUB_TOKEN

Variables:
RALPH_API_BASE_URL
RALPH_API_MODEL
RALPH_LANG=zh-CN

3. Trigger work

/ralph
Goal: redesign the homepage
Requirements: modern style, responsive layout
Constraints: keep current stack
Acceptance: mobile works, no console errors

View Repository Feishu Setup Architecture Notes

Use Cases

Where Ralph fits best

Overnight feature delivery

Queue scoped issues during the day and wake up to a draft PR with validator feedback.

Large refactors

Break risky rewrites into planned runnable slices while preserving issue and PR continuity.

Team chat to repo workflow

Use Feishu for ingress and approvals, while every execution artifact stays anchored in GitHub.

Cross-repo automation

Operate a central Ralph deployment that can dispatch into other repositories with clear routing.

Docs

Go deeper when you are ready to integrate Ralph into real work

The product site is for orientation. The repository docs remain the detailed source for setup, architecture, Feishu integration, and contribution flow.

README

Overview, architecture, execution model, and setup instructions in English.

Open README

README_CN

Chinese documentation for setup, concepts, and workflow expectations.

打开中文文档

Feishu & Architecture

Deployment details, routing, and orchestration notes for real-world usage.

Open Feishu docs