Usage Guide

Prerequisites

• Node.js 18+ and npm installed on your host machine
• VS Code with the Dev Containers extension and Docker / Colima (optional for isolation)
• A GitHub account with CLI logged in (optional — only needed for remote push)

Getting Started

Create a new empty project folder, open a terminal inside it, then run:

mkdir my-project && cd my-project
npx ralph-workflow

The wizard will ask:

1. Dev Container template — choose Node, Python, Ubuntu, etc.
2. GitHub access — optionally create a fine-grained PAT scoped to one repo.
3. AI CLI — pick claude, codex, gemini, or opencode.

Set Up Isolation via Dev Container (Optional)

You will be prompted whether you want to set up a VS Code Dev Container for isolation. If yes, you can select from available Dev Container templates (e.g. Node, Python, Ubuntu). Git access is configured before devcontainer.json is created.

After the wizard completes, open the folder in VS Code and reopen it in a container:

1. Open the project folder in VS Code.
2. Install the Dev Containers extension if not already installed.
3. Click the >< icon in the bottom-left corner, then select Reopen in Container (or use Cmd+Shift+P → Dev Containers: Reopen in Container).

A postStart script runs automatically to clean up any credentials VS Code may have forwarded from your host machine. VS Code's Dev Containers extension automatically forwards git credentials by default. By default ralph-workflow applies aggressive cleanup so you are explicitly in control of what credentials Ralph can access.

Configuring Git Granular Access (Optional)

Giving Ralph access to a remote GitHub repository is optional — Ralph works fine with local git only. If you want Ralph to push to a remote repo, set up a fine-grained PAT during the wizard:

1. The wizard creates a GitHub repo using your current local git credential (you can retry or skip if it fails).
2. The shell provides a GitHub link to create a PAT with the recommended minimum permissions pre-filled in the URL parameters.
3. Open the link, manually select the repository you want Ralph to access, and generate the token.
4. Paste the token back into the shell — it will be stored on your host and mounted into the Dev Container.

This gives Ralph access to only that one repo with granular permissions, reducing blast radius if something goes wrong.

(Important) Setting Up Your AI CLI

ralph-workflow is designed to automatically install your chosen AI CLI in the container. You must configure it once before Ralph can run it unattended.

For Claude Code:

# Inside the container terminal:
claude                                     # log in
claude --dangerously-skip-permissions      # accept the warning once

The --dangerously-skip-permissions acceptance only needs to happen once per container.

Writing prd.yaml Stories

Open scripts/ralph/prd.yaml and define your stories. Use your AI assistant or write them manually:

branchName: ralph/feature
userStories:
  - id: US-001
    title: Add login form
    acceptanceCriteria:
      - Email/password fields
      - Validates email format
      - typecheck passes
    priority: 1
    passes: false
    notes: ""

• branchName — Ralph will commit to this branch.
• priority — lower number = implemented first.
• passes — Ralph sets this to true when the story is complete.
• acceptanceCriteria — concrete, testable conditions Ralph must satisfy.

Defining Project Direction with main_prd.md (Optional)

A main_prd.md template is scaffolded for you. It acts as your "product manager" document — containing basic guidelines, user identification, requirements, and high-level objectives.

If you have rough ideas, ask your AI assistant to help turn them into a main_prd.md. Polish this document yourself before running Ralph so it doesn't build in the wrong direction. If you already have clear requirements or just want to dive in, you can ignore this file.

Once your direction is clear, break goals into smaller stories in scripts/ralph/prd.yaml.

Seeding progress.txt

Before the first run, seed scripts/ralph/progress.txt with codebase context. Ralph appends a new entry after every story — patterns accumulate across iterations and are visible on the next run.

# Ralph Progress Log

## Codebase Patterns
- Migrations: IF NOT EXISTS
- Types: Export from actions.ts

## Key Files
- db/schema.ts
- app/auth/actions.ts
---

Running ralph.sh

Inside the container terminal, make the script executable and run it:

chmod +x scripts/ralph/ralph.sh
./scripts/ralph/ralph.sh 25   # up to 25 iterations

Each iteration Ralph will:

1. Read prd.yaml for the next incomplete story.
2. Read progress.txt for accumulated codebase patterns.
3. Implement the story, run typechecks and tests.
4. Commit the change.
5. Mark the story passes: true and append learnings to progress.txt.
6. Output <promise>COMPLETE</promise> when all stories are done.

The loop exits with code 0 on completion, or code 1 if MAX_ITERATIONS is reached first.

Scaffolded Files

scripts/ralph/
├── ralph.sh          # the iteration loop
├── prompt.md         # per-iteration instructions for Claude
├── prd.yaml          # your task list (edit this before running)
└── progress.txt      # accumulated learnings (start with codebase context)

The prompt.md instructs Ralph on each iteration:

# Ralph Agent Instructions

## Your Task

1. Read `scripts/ralph/prd.yaml`
2. Read `scripts/ralph/progress.txt`
3. Pick highest priority story where `passes: false`
4. Implement that ONE story
5. Run typecheck and tests
6. Commit: `feat: [ID] - [Title]`
7. Update prd.yaml: `passes: true`
8. Append learnings to progress.txt

Tips

Running Docker

Use Colima to provide a Docker runtime — it's open source and commercially safe. Docker Desktop works too, but be aware of its commercial licensing terms.

Container Resource Defaults

When running in container mode, resources are often restricted by default. It's recommended to bump up CPU and memory allocation to prevent a slow isolated development environment.