ralph-unpossible

Autonomous coding loop runner. Ralph takes a YAML task list and runs an AI agent iteratively until all tasks are done — no more, no less.

• Requires Node.js >= 22

Install

# Run without installing
npx @crcatala/ralph-unpossible --help

# Or install globally
npm install -g @crcatala/ralph-unpossible

From source

git clone https://github.com/crcatala/ralph-unpossible
cd ralph-unpossible
npm install
npm run build
npm link   # optional: makes `ralph` available on your PATH

See RELEASING.md for maintainer release instructions.

Usage

Ralph uses a .ralph/ folder in your project and discovers the nearest one by walking upward from cwd.

# create a new loop
ralph new my-loop

# list and validate loops
ralph list
ralph validate my-loop

# run until no pending tasks remain
ralph run my-loop

# archive a completed loop
ralph archive my-loop

ralph run uses pi by default; switch runners with --agent (e.g. opencode) or a custom command via --agent <cmd> --agent-arg <arg> ....

Project Layout

.ralph/
  loops/<loop>/
    prd.yaml          # task definitions
    progress.md        # learnings log (auto-created)
    guardrails.md      # constraints (auto-created on first run)
  templates/           # optional per-project prompt overrides
  loops-archived/      # created by `ralph archive`

Pull Request Creation

When a loop completes, Ralph can automatically create a pull request if create_pr: true is set in prd.yaml.

Requirements: GitHub CLI (gh) installed and authenticated, pushable branch.

create_pr: true               # Enable automatic PR creation
pr_title: "feat: my feature"  # Optional (defaults to loop name)
pre_commit: "npm test"        # Shown in PR verification section
description: |                # Fallback PR summary
  What this loop implements

Ralph generates an AI summary for the PR using Claude Haiku from completed tasks, commit messages, and the git diff. If AI generation fails, it falls back to the description field.

Skip PR creation even when enabled: ralph run my-loop --no-pr

Sessions & State

Each iteration writes a session folder — default: ~/.ralph/sessions/<loop>/<NNN>/ (base directory can be overridden with RALPH_HOME).

Each session contains:

• prompt.md — rendered prompt sent to the agent
• output.log — captured stdout/stderr
• meta.json — task label, model info, exit code, timings

Ralph also persists a circuit-breaker state file at ~/.ralph/state/<project-hash>/<loop>/state.json. If a run halts due to stagnation or repeated failures, inspect the most recent session output and delete the state.json to reset.

Development

npm install
npm test
npm run build
node dist/cli.js --help

Releasing

See RELEASING.md — changelog preparation, version bump, npm publish, and GitHub Release via release-it.