Ralph Loop

Autonomous implementation loop for spec-kit. Ralph repeatedly spawns a fresh AI agent that reads your tasks.md, implements the next work unit, commits the result, and loops until every task is done.

Prerequisites

Requirement	Why
spec-kit (`specify` CLI) >= 0.8.5	Extension host — provides project structure, task management, and integration metadata used for skills-mode dispatch
GitHub Copilot CLI, OpenAI Codex CLI, or Claude Code	Agent CLI used to execute each iteration (`copilot` is the default)
Git	Version control — Ralph commits completed work units automatically

Your project must be initialized with specify init and have a feature branch checked out with a completed tasks.md.

Installation

specify extension add ralph

Or install from repository directly

specify extension add ralph --from https://github.com/Rubiss-Projects/spec-kit-ralph/archive/refs/tags/v1.2.1.zip

Verify the installation:

specify extension list
# ✓ Ralph Loop (v1.2.1)
#   Autonomous implementation loop using AI agent CLI
#   Commands: 2 | Hooks: 1 | Status: Enabled

The installed extension includes .specify/extensions/ralph/ralph-config.yml for project defaults and registers the iterate command for your active agent. No post-install config copy step is required.

Usage

Path 1 — Agent Command

Run inside an agent session that supports spec-kit extension commands:

/speckit.ralph.run

With options:

/speckit.ralph.run --max-iterations 5 --model gpt-5.1

The command validates prerequisites, detects the current feature context, and delegates to the platform-appropriate orchestrator script.

Only launcher flags are accepted here. Free-form text such as Implement US1 is ignored by the launcher because Ralph selects the next incomplete work unit from tasks.md inside the orchestrated iteration.

Path 2 — Direct Script Invocation

Run the orchestrator scripts directly from your terminal for debugging or CI use.

PowerShell (Windows):

.specify/extensions/ralph/scripts/powershell/ralph-loop.ps1 `
  -FeatureName "001-my-feature" `
  -TasksPath "specs/001-my-feature/tasks.md" `
  -SpecDir "specs/001-my-feature" `
  -MaxIterations 10 `
  -Model "claude-sonnet-4.6" `
  -AgentCli "copilot"

Bash (macOS / Linux):

.specify/extensions/ralph/scripts/bash/ralph-loop.sh \
  --feature-name "001-my-feature" \
  --tasks-path "specs/001-my-feature/tasks.md" \
  --spec-dir "specs/001-my-feature" \
  --max-iterations 10 \
  --model "claude-sonnet-4.6" \
  --agent-cli "copilot"

Configuration

Edit .specify/extensions/ralph/ralph-config.yml to customize defaults:

# AI model for agent iterations
model: "claude-sonnet-4.6"

# Maximum loop iterations before stopping
max_iterations: 10

# Path or name of the agent CLI binary
# Supported: copilot, codex, claude
agent_cli: "copilot"

Ralph also ships .specify/extensions/ralph/ralph-config.template.yml as a reference copy of the defaults. Use it to compare or reset configuration; the active project config is ralph-config.yml.

Agent CLI Support

Ralph supports CLI-specific invocation codepaths selected by agent_cli.

`agent_cli`	Invocation shape	Notes
`copilot`	`copilot --agent speckit.ralph.iterate -p ... --model ... --yolo -s` or `copilot -p "/speckit-ralph-iterate ..." --model ... --yolo -s`	Default path. Resolves the registered command/skill name from `.specify/integration.json`: dot separator uses `--agent speckit.ralph.iterate`; dash/skills mode invokes `/speckit-ralph-iterate` in the prompt. Spec Kit integration options such as `--skills` are not passed as Copilot runtime flags.
`codex`	`codex exec --json --model ... --sandbox danger-full-access --cd ... -`	Uses Codex non-interactive mode and passes the existing `speckit.ralph.iterate` command text via stdin.
`claude`	`claude -p ... --model ... --dangerously-skip-permissions`	Uses Claude Code print/non-interactive mode. Passes the existing `speckit.ralph.iterate` command text in the prompt (Claude Code has no registered agent to select). `--dangerously-skip-permissions` runs unattended (equivalent to `--permission-mode bypassPermissions`).

To use Codex:

model: "gpt-5.3-codex"
max_iterations: 10
agent_cli: "codex"

Install and authenticate the Codex CLI first. Ralph does not store Codex API keys or ChatGPT credentials in its config.

To use Claude Code:

model: "claude-sonnet-4-6"
max_iterations: 10
agent_cli: "claude"

Install and authenticate Claude Code (claude) first. Ralph passes --dangerously-skip-permissions so iterations run unattended — only use this in a trusted working directory. Ralph does not store Anthropic API keys or credentials in its config.

Configuration Precedence

Settings are resolved from lowest to highest priority:

Priority	Source	Example
1 (lowest)	Extension defaults	Hardcoded in `extension.yml`
2	Project config	`.specify/extensions/ralph/ralph-config.yml`
3	Local overrides	`.specify/extensions/ralph/ralph-config.local.yml` (gitignored)
4	Environment variables	`SPECKIT_RALPH_MODEL`
5 (highest)	CLI parameters	`--model`, `--max-iterations`

Environment Variables

Variable	Description	Default
`SPECKIT_RALPH_MODEL`	AI model to use	`claude-sonnet-4.6`
`SPECKIT_RALPH_MAX_ITERATIONS`	Maximum iterations before stopping	`10`
`SPECKIT_RALPH_AGENT_CLI`	Agent CLI binary name or path	`copilot`

export SPECKIT_RALPH_MODEL="gpt-5.3-codex"
export SPECKIT_RALPH_MAX_ITERATIONS="20"
export SPECKIT_RALPH_AGENT_CLI="codex"

Note: Never store authentication tokens in the config file. Use GH_TOKEN or GITHUB_TOKEN environment variables for authentication.

How the Loop Works

┌─────────────────────────────────────────┐
│           ralph-loop starts             │
│  validate prerequisites, load config    │
└──────────────────┬──────────────────────┘
                   ▼
          ┌────────────────┐
          │ Any tasks left?│──No──▶ exit 0 (COMPLETED)
          └───────┬────────┘
                  │ Yes
                  ▼
  ┌───────────────────────────────┐
  │  Spawn fresh agent process    │
  │  configured agent CLI runs    │
  └──────────────┬────────────────┘
                 ▼
  ┌───────────────────────────────┐
  │  Agent reads tasks.md +       │
  │  progress.md, implements      │
  │  ONE work unit, commits       │
  └──────────────┬────────────────┘
                 ▼
       ┌──────────────────┐
       │ Check termination│
       │   conditions     │
       └────────┬─────────┘
                ▼
        back to "Any tasks left?"

Iteration Cycle

The orchestrator spawns a fresh configured agent CLI process each iteration.
The agent reads tasks.md to find the first incomplete work unit (phase, user story, or task group).
It implements tasks within that single work unit, marks them [x] in tasks.md, and commits on completion.
It appends an iteration entry to progress.md with files changed and lessons learned.
Control returns to the orchestrator, which checks termination conditions and loops.

Termination Conditions

Condition	Exit Code	Meaning
All tasks in `tasks.md` marked `[x]`	`0`	Success — nothing left to do
Agent outputs `<promise>COMPLETE</promise>`	`0`	Agent confirmed all work is done
Max iterations reached	`1`	Safety limit — increase `max_iterations` if needed
3 consecutive failures	`1`	Circuit breaker — agent is stuck
Ctrl+C	`130`	User interrupted the loop

Resuming After Interruption

Ralph is designed to be interrupted and resumed safely. Each iteration is self-contained: tasks are marked [x] in tasks.md and progress is logged in progress.md as work completes.

To resume, simply re-run the command:

/speckit.ralph.run

Or re-run the script directly. The orchestrator reads the current checkbox state in tasks.md and skips completed tasks. The progress.md log gives the agent context from prior iterations.

Extension Structure

spec-kit-ralph/
├── extension.yml                  # Extension manifest (schema v1.0)
├── commands/
│   ├── run.md                     # speckit.ralph.run — thin launcher
│   └── iterate.md                 # speckit.ralph.iterate — single iteration
├── scripts/
│   ├── powershell/
│   │   └── ralph-loop.ps1         # PowerShell orchestrator
│   └── bash/
│       └── ralph-loop.sh          # Bash orchestrator
├── ralph-config.yml               # Installed project config
├── ralph-config.template.yml      # Config template
├── README.md
├── CHANGELOG.md
└── LICENSE                        # MIT

ralph