ralph-teams - Loop epics and ai teams, Trust the Team-Lead, Run and Walk away

Lightweight orchestration for spec-driven AI delivery: Ralph Teams loops whole teams and epics, not tiny tasks, and uses small agent teams to move from PRD to merged implementation with minimal process overhead.

The Teamlead decides on which agent to spawn and which model to use depending on the task complexity.

It is built for developer who don't want to babysit their agents. Start the loop and walk away.

ralph-teams is a lightweight and budgetfriendly CLI for running Ralph Teams: a shell-based orchestrator that initializes and reads a prd.json, loops through epics (not user stories), and spawns AI coding agent teams to implement work story by story. One Agent Team per Epic with fresh context. Ralph-Teams can even work on multiple epics in parallel, if there are no dependencies

ralph-teams run --parallel={max_parallel_epics}

Why Use Ralph-Teams

Many spec-driven tools are heavy, burn a lot of tokens, and are harder to adapt when the underlying agent capabilities change. Ralph's original idea was to trust the agent more and keep orchestration light. That bias fits the current direction of AI tooling: agents keep getting better, context windows keep growing, and models are increasingly able to coordinate teams of sub-agents on their own.

ralph-teams is built around that idea. Instead of heavy process layers, it loops whole epics with small agent teams and keeps the orchestration simple and configurable. In my experience, the epic and user-story structure tends to work well because the user-centric view and explicit acceptance criteria give the agents a clearer picture of what "done" means.

The default balanced mode is intentionally simple:

• the Team Lead orchestrates the epic
• for clearly easy, low-risk mechanical work, the Team Lead may implement directly
• it can spawn the epic planner if needed
• it spawns one Builder per story attempt
• it validates inline or spawns a validator when independent verification is needed
• it works through the user stories sequentially until the epic is done
• Ralph then moves to the next epic until all epics are done

Quickest Start

npm install -g ralph-teams

# discuss with an agent and create the prd.json (epics and user stories)
ralph-teams init

# start the loop, by default uses claude
ralph-teams run

Flow

This diagram shows the default balanced workflow only.

flowchart TD
    A[Start run] --> B[Validate PRD and create loop branch plus loop worktree]
    B --> C[Pick ready epic]
    C --> D[Create epic worktree and run-scoped epic branch]
    D --> E[Team Lead decides on epic planner]
    E --> F[Team Lead runs stories with builder]
    F --> G{Epic validator needed?}
    G -->|No| J[Team Lead merges epic branch and writes merge artifact]
    G -->|Yes| H[Run epic validator]
    H -->|PASS| J
    H -->|FAIL and retries left| I[Builder fixes epic-level findings]
    I --> H
    J --> K[If needed, fallback merge recovery handles leftovers]
    K --> L{More epics?}
    L -->|Yes| C
    L -->|No| P[Finish]

Other presets:

• full: adds optional story planner and optional story validator decisions inside each epic.
• minimal: disables planner and validator subagent stages. The Team Lead still coordinates builders and records per-story pass/fail results.

What It Does

At a high level:

• ralph.sh owns the run loop, worktrees, merges, resume state, and backend process lifecycle.
• one Team Lead session runs per epic and delegates to planner, builder, validator, and merger roles as needed, or implements trivial work directly.
• ralph.config.yml controls backend choice, workflow toggles, parallelism, timeouts, and model selection.

Workflow presets:

• balanced: epic planning enabled, heuristic epic validation enabled (no final validation)
• full: balanced, plus story planning, heuristic story validation, and final validation
• minimal: planning and validation toggles disabled; no planner or validator subagents are spawned

Default agent model assignments:

• teamLead: opus
• epicPlanner: opus
• epicValidator: opus
• finalValidator: opus
• builder: sonnet
• storyValidator: sonnet
• storyPlanner: opus
• merger: sonnet

Ralph never writes code itself. It only schedules work, tracks results, and updates project state.

For detailed workflow semantics, validation behavior, config precedence, runtime files, and architecture, see docs/architecture.md.

Current backends:

• claude via the claude CLI and .claude/agents/*.md
• copilot via gh copilot and .github/agents/*.agent.md
• codex via the codex CLI, repo-local .codex/agents/*.toml, and Codex multi-agent mode
• opencode via the opencode CLI and .opencode/agents/*.md
• shared worker-agent prompt source in prompts/agents/*.md, rendered to those backend-specific files via npm run sync:agents

Requirements

• Node.js 18+
• Git available if you want Ralph to switch/create the target branch

Backend-specific requirements:

• Claude backend:
  • claude CLI in PATH
• Copilot backend:
  • gh CLI in PATH
  • GitHub Copilot CLI available through gh copilot
• Codex backend:
  • codex CLI in PATH
  • multi-agent feature enabled by the CLI (Ralph passes --enable multi_agent automatically)
• OpenCode backend:
  • opencode CLI in PATH

Install

Install globally:

npm install -g ralph-teams

Or use it locally from this repo:

npm install
npm run build
npm link

Then verify:

ralph-teams --help
rjq --help

Start

1. Create a PRD:

ralph-teams init

2. Validate it:

ralph-teams validate

3. Inspect the planned work:

ralph-teams summary
ralph-teams status

4. Run Ralph:

ralph-teams run

5. Check progress:

ralph-teams logs

Run ralph.sh directly when you want shell-level flags:

./ralph.sh prd.json --backend claude
./ralph.sh prd.json --backend copilot
./ralph.sh prd.json --backend codex
./ralph.sh prd.json --parallel 2
./ralph.sh prd.json --backend copilot --max-epics 1

Commands

ralph-teams setup

Runs interactive setup to create or update ralph.config.yml for your repository.

ralph-teams setup

Prompts for:

• Default backend (claude, copilot, codex, opencode)
• Planning/validation workflow setup: use a preset or configure each planning and validation step manually
• Workflow preset (balanced, full, minimal) with short inline explanations during setup
• Parallel epic execution and max parallel epics
• Overall loop timeout
• Agent model overrides (optional)

Workflow presets:

• balanced: epic planning enabled, heuristic epic validation enabled (no final validation)
• full: balanced, plus story planning, heuristic story validation, and final validation
• minimal: planning and validation toggles disabled; no planner or validator subagents are spawned

Preset behavior notes:

• minimal still lets the Team Lead validate stories inline and mark them passed or failed; it only disables the separate planner/validator subagent stages.

ralph-teams init

Creates a new prd.json interactively in the current directory by launching an AI PRD-creator session. If ralph.config.yml does not already exist, init first runs interactive setup so you can configure Ralph for the repository.

ralph-teams init
ralph-teams init --backend claude
ralph-teams init --backend copilot
ralph-teams init --backend codex
ralph-teams init --backend opencode

Flow:

1. init launches an interactive agent session
2. the agent discusses the product with you directly
3. the agent asks follow-up questions until the requirements are clear
4. the agent generates the full prd.json with project metadata, epics, and user stories
5. if ./ralph.config.yml is missing, init first runs ralph-teams setup interactively and writes the chosen config
6. the agent writes ./prd.json
7. after writing the PRD, the init agent can either continue into implementation planning with you or stop there if you want to skip planning for now

Notes:

• init is grounded by prd.json.example
• init does not overwrite an existing ralph.config.yml
• setup lets you choose the default backend, use a planning/validation workflow preset or configure that workflow manually, set parallelism, and optionally override per-role models
• the agent generates epics and user stories automatically
• the agent should aim for about 5 user stories per epic when the scope supports it
• treat about 5 user stories as the current practical ceiling for an epic, not just a suggestion; this keeps the Team Lead session context under control and avoids overwhelming the epic planner
• --backend controls whether the interview/generation uses claude, copilot, codex, or opencode
• the discussion itself is handled by the agent, not by a hardcoded questionnaire in the CLI

ralph-teams run [path]

Runs Ralph against a PRD file. Default path is ./prd.json.

ralph-teams run
ralph-teams run ./my-prd.json
ralph-teams run --backend copilot
ralph-teams run --backend codex
ralph-teams run --parallel 2

Behavior:

• validates that the selected backend dependencies, rjq, and the PRD are available
• locates bundled ralph.sh
• streams Ralph output directly to the terminal
• exits with Ralph's exit code

Notes:

• --backend is forwarded to ralph.sh
• runs sequentially by default
• --parallel <n> enables the experimental parallel wave runner

Planning behavior:

• if an epic has planned: true, the Team Lead is expected to read .ralph-teams/plans/plan-EPIC-xxx.md and follow it
• if an epic is still unplanned and epic planning is enabled, medium- and high-complexity epics should spawn the epic planner before implementation
• only clearly low-complexity epics should skip planning during execution

ralph-teams task <prompt>

Runs an ad hoc task in the current repository without creating a PRD, epic, or story structure.

ralph-teams task "fix the flaky auth test"
ralph-teams task "add rate limiting to login" --backend codex

Behavior:

• requires a checked out git branch and runs on that same branch
• asks once whether you want to plan the task first
• if you choose planning, starts a guided planning session with the agent
• otherwise starts direct Team Lead execution for the task

Notes:

• this mode does not create prd.json entries or worktrees
• --backend controls whether the task uses claude, copilot, or codex

ralph-teams plan [path]

Starts a guided planning discussion for epics that are not yet marked as planned. Default path is ./prd.json.

ralph-teams plan
ralph-teams plan ./my-prd.json
ralph-teams plan --backend claude

Behavior:

• loads epics with planned !== true
• starts an interactive agent discussion about implementation approach and sequencing
• asks the agent to write .ralph-teams/plans/plan-EPIC-xxx.md
• asks the agent to mark each agreed epic as planned: true in prd.json

Notes:

• this command is intended after ralph-teams init
• if you skip an epic during planning, it remains planned: false
• planned epics should not require the Team Lead to spawn another epic planner later

ralph-teams resume

Resumes an interrupted run from ./.ralph-teams/ralph-state.json.

ralph-teams resume

Behavior:

• reloads the saved PRD path, backend, and parallel settings
• reuses the current project config for timeouts and workflow settings
• restarts ralph.sh
• removes .ralph-teams/ralph-state.json after a successful resume

ralph-teams status [path]

Shows epic and story pass/fail state from a PRD.

ralph-teams status
ralph-teams status ./my-prd.json

ralph-teams logs [--tail N]

Shows .ralph-teams/progress.txt with light colorization.

ralph-teams logs
ralph-teams logs --tail 20

--tail shows the last N wave blocks from .ralph-teams/progress.txt.

ralph-teams reset [epicId] [path]

Resets one epic to pending and sets all of its stories back to passes: false. When no epic ID is provided, resets all epics.

ralph-teams reset EPIC-002
ralph-teams reset          # resets all epics

ralph-teams validate [path]

Validates PRD structure and dependency integrity.

ralph-teams validate

Checks include:

• required fields
• valid epic status values
• duplicate epic IDs
• duplicate story IDs
• invalid dependsOn values
• unknown dependsOn references
• circular epic dependencies

ralph-teams summary [path]

Prints a dependency-oriented overview of epics.

ralph-teams summary

Shows:

• dependency arrows
• epic status
• story pass counts
• blocked epics

Backends

Claude Backend

Uses:

• claude CLI
• canonical worker prompts in prompts/agents/
• .claude/agents/
• structured JSON streaming from the Claude CLI

Example:

./ralph.sh prd.json --backend claude

Copilot Backend

Uses:

• gh copilot
• canonical worker prompts in prompts/agents/
• .github/agents/
• PTY-backed execution so live Copilot output is visible during runs

Example:

./ralph.sh prd.json --backend copilot

Notes:

• Copilot live output is routed through a PTY wrapper in ralph.sh
• without the PTY wrapper, gh copilot may not show incremental output in pipe mode
• Copilot difficulty-based defaults now use GPT-family models: gpt-5-mini, gpt-5.3-codex, and gpt-5.4

Codex Backend

Uses:

• codex exec
• canonical worker prompts in prompts/agents/
• .codex/agents/*.toml
• Codex multi-agent mode with repo-local scoped planner, builder, and validator roles

Example:

./ralph.sh prd.json --backend codex

Notes:

• Ralph enables Codex multi-agent mode per run, so no global ~/.codex/config.toml edits are required
• Codex runs from each epic worktree and is granted write access to the repo root so it can update the shared PRD
• Codex does not use a separate repo-local Team Lead role file; the Team Lead policy comes from the runtime prompt assembled in ralph.sh, while .codex/agents/*.toml define the spawned story-planner, epic-planner, builder, story-validator, epic-validator, final-validator, and merger roles
• Codex follows the same scoped planning/validation contract as Claude and Copilot; the runtime prompt in ralph.sh enforces that policy for Codex Team Leads
• Edit prompts/agents/*.md and run npm run sync:agents to regenerate the backend-specific worker agent files

OpenCode Backend

Uses:

• opencode CLI
• canonical worker prompts in prompts/agents/
• .opencode/agents/

Example:

./ralph.sh prd.json --backend opencode

PRD Format

Example:

{
  "project": "MyApp",
  "branchName": "main",
  "description": "Short description of the project",
  "epics": [
    {
      "id": "EPIC-001",
      "title": "Authentication",
      "description": "Add login and session handling",
      "status": "pending",
      "planned": false,
      "dependsOn": [],
      "userStories": [
        {
          "id": "US-001",
          "title": "Login form",
          "description": "As a user, I want to sign in",
          "acceptanceCriteria": [
            "User can submit email and password",
            "Validation errors are shown clearly"
          ],
          "priority": 1,
          "passes": false,
          "failureReason": null
        }
      ]
    }
  ]
}

Important fields:

• epics[].status: pending | completed | partial | failed | merge-failed
• epics[].planned: whether the implementation plan for this epic has already been created and agreed
• epics[].dependsOn: epic IDs that must be completed first
• userStories[].passes: whether the story is currently marked as passing
• userStories[].failureReason: short reason for the latest failed attempt, or null

Authoring guideline:

• aim for about 5 user stories per epic when the scope can be split cleanly
• treat about 5 user stories as the current practical ceiling for an epic so the Team Lead session stays within a reasonable context window and the epic planner is not overloaded
• use fewer only when the epic is genuinely small or further splitting would be artificial

The init command uses prd.json.example as schema and style guidance when generating a new PRD.

Files Ralph Produces

During a run, Ralph writes:

• .ralph-teams/progress.txt: high-level run log
• .ralph-teams/.worktrees/EPIC-xxx/: isolated git worktree for an active epic
• .ralph-teams/state/EPIC-xxx.json: per-epic story pass/fail state (Team Lead reads/writes)
• .ralph-teams/state/merge-EPIC-xxx.json: per-epic merge-result artifact written by the Team Lead or merge recovery path
• .ralph-teams/plans/plan-EPIC-xxx.md: epic-planner output for an epic
• planned epics are expected to use these files as their implementation contract
• .ralph-teams/logs/loop-<timestamp>.log: outer ralph-teams run orchestration log mirroring terminal output
• .ralph-teams/logs/epic-EPIC-xxx-<timestamp>.log: raw backend session log
• .ralph-teams/ralph-state.json: saved interrupt/resume state

Ralph also updates the original prd.json in place as epic status changes.

The outer run log and the team lead agent log for each epic are written to .ralph-teams/logs/ regardless of backend.

Runtime Rules

The current execution contract is:

• Ralph loops through epics in PRD order
• blocked epics are skipped until dependencies are complete
• runs sequentially by default
• experimental wave parallelism is enabled only with --parallel <n>
• at run start Ralph auto-commits any dirty source-worktree changes, then creates a fresh loop branch and checks it out in .ralph-teams/.worktrees/loop
• each epic gets its own worktree and a run-scoped branch rooted from that loop branch, using ralph/epic/<loop-run>/<epic-id>
• before the Team Lead starts, Ralph creates the worktree and expects the Team Lead to establish that epic worktree's setup once, then hand the exact bootstrap, build, and test commands to Builders
• agents are expected to prefer repo-defined scripts and docs over generic ecosystem defaults when choosing setup and verification commands
• the shell-built Team Lead prompt must keep literal filenames shell-safe; do not add raw Markdown backticks inside that Bash string because Bash will treat them as command substitution
• when an epic completes successfully, the Team Lead is expected to merge its epic branch back into the loop branch and write the merge-result artifact
• the backend team processes one epic per session
• stories run sequentially inside that epic
• already-passed stories are skipped
• rerunning Ralph automatically resets failed and partial epics back to pending so only unfinished work is retried
• each story gets at most two build/validate cycles
• Builder and Validator are one-shot story-scoped workers, never long-lived mailboxes shared across stories
• a Builder attempt only counts when the Team Lead receives a concrete commit SHA for that story attempt
• scoped validators check output independently from the builder's reasoning
• the Team Lead is expected to delegate early and not inspect the codebase beyond the minimum needed before delegation
• for clearly easy, low-risk mechanical tasks, the Team Lead may implement directly instead of delegating
• DONE: X/Y stories passed is a required session footer, but it is not enough to complete an epic on its own
• the durable epic-completion contract is: projected story state plus a valid merge-result artifact
• if PRD state says an epic is pending but the current loop branch already contains prior merge history for that run-scoped epic branch, Ralph fails fast instead of silently reusing stale history
• pressing Ctrl-C writes .ralph-teams/ralph-state.json so the run can be resumed later with ralph-teams resume

Troubleshooting

zsh: command not found: ralph-teams

Install or relink the package:

npm install -g ralph-teams

Or from this repo:

npm link

The package also installs rjq, which ralph.sh uses internally.

Error: 'claude' CLI not found

Install Claude Code and ensure claude is on your PATH.

Error: 'gh' CLI not found

Install GitHub CLI and ensure gh is on your PATH.

Error: 'codex' CLI not found

Install Codex CLI and ensure codex is on your PATH.

Error: 'opencode' CLI not found

Install OpenCode CLI and ensure opencode is on your PATH.

Error: GitHub Copilot CLI not available

Make sure gh copilot is installed and working:

gh copilot -- --version

Copilot backend runs but shows no live output

This repo runs Copilot through a PTY wrapper in ralph.sh because plain pipe mode does not reliably stream visible output from gh copilot.

If output still looks stuck, test the backend directly:

./ralph.sh prd.json --backend copilot --max-epics 1

If that still does not stream, the issue is likely in the local gh copilot environment rather than the CLI wrapper.

Install Claude Code and ensure claude is on your PATH.

Error: 'rjq' not found

Install or relink the package so the bundled JSON CLI is on your PATH:

npm install -g ralph-teams

Ralph needs a clean base commit before creating the loop worktree

Ralph auto-commits current source-worktree changes before creating the loop branch and loop worktree. If you do not want that commit, clean up the worktree yourself before starting the run.

Development

Useful commands in this repo:

npm run build
npm run typecheck
npm test
npm link

Packaged binaries:

• ralph-teams: main CLI entrypoint (dist/index.js)
• rjq: bundled JSON query/manipulation CLI used by ralph.sh (dist/json-tool.js)

The runtime orchestrator is ralph.sh.