Skip to content
ralph

Quick Start

Quick Start

Section titled “Quick Start”

Let’s run your first ralph loop. We’ll add tests to a simple project—the kind of tedious, repetitive work that ralph excels at.

The 5-Minute Version

Section titled “The 5-Minute Version”

  1. Initialize ralph

    Terminal window
    cd your-project
    ralph init

    Select your adapter (claude recommended) when prompted.

  2. Edit your prompt

    Open .plans/PROMPT.md and add your task:

    @.plans/prd.json @.plans/progress.txt
    run `git log --limit 10`
    

    1. Select the highest-priority feature to work on and work ONLY on that feature. This should be the one YOU decide has the highest priority - not necessarily the first in the list. `cat .plans/prd.json | jq '[.[] | select(.passes == false)]'`
    2. Before making changes, search codebase (don't assume not implemented).
    3. Implement the requirements for the selected feature using TDD.
    3. Run typecheck and tests: `bun run typecheck && bun run test`
    4. Update prd.json marking completed work (CAREFULLY!)
        **YOU CAN ONLY MODIFY ONE FIELD: "passes"**
        After thorough verification, change:
        ```json
        "passes": false
        ```
        to:
        ```json
        "passes": true
        ```
    5. Reflect on what you have done and APPEND learning to .plans/progress.txt for future iterations.
    6. Commit changes: `git add . && git commit -m "<description/>"`
    7. If all features complete, output `<promise>COMPLETE</promise>`
    

    

    IMPORTANT RULES:
    - ONLY WORK ON A SINGLE FEATURE PER ITERATION.
    - When you learn something new about how to run commands or patterns in the code make sure you update @CLAUDE.md using a subagent but keep it brief.
    - If you find a bug or issue, add it to the .plans/next.md
    

    REMEMBER: You have unlimited time across many sessions. Focus on quality over speed. Production-ready is the goal.

  3. Use your agent to plan

    • Use the ralph-prd skill

    or

    • Use your ai tool create a plan for the functionlality you want to implememt.
    • Review the plan and make any required changes.
    • Ask your AI to break down the plan into the ralph prd.json file

  4. Run the loop

    Terminal window
    ralph run

That’s it. ralph will:

  1. Start your AI tool with the prompt
  2. Let it work until it exits
  3. Reset context and feed the same prompt
  4. Repeat until the AI outputs <promise>COMPLETE</promise> or max iterations

The run ends when:

  • AI outputs <promise>COMPLETE</promise> (success)
  • Max iterations reached
  • User interrupts (Ctrl+C)
  • Error occurs

Common Patterns

Section titled “Common Patterns”

Prompt that can be used without needing the prd.json

Pattern 1: Fix All Errors

Section titled “Pattern 1: Fix All Errors”
@.plans/progress.txt
run `git log --limit 10`


Fix all ESLint errors.


## Process
1. Run `npm run lint` to see errors.
2. Select a single file with errors. Only update a single file at a time.
3. Add make the required change to fix the errors.
4. Run typecheck and tests to verify correctness.
5. Reflect on what you have done and APPEND learning to .plans/progress.txt for future iterations.
6. Commit changes with a descriptive message.




## Completion
When `npm run lint` exits with code 0, output:
<promise>COMPLETE</promise>

Pattern 2: Migration

Section titled “Pattern 2: Migration”
@.plans/progress.txt
run `git log --limit 10`


Migrate all usages of `oldApi` to `newApi`.


1. Find work
   `grep -r "oldApi" src/`


2. Select the first file. Only update a single file at a time.
3. Make the required change to migrate the api.
4. Run typecheck and tests to verify correctness.
5. Reflect on what you have done and APPEND learning to .plans/progress.txt for future iterations.
6. Commit changes with a descriptive message.


## Migration rules
- `oldApi.fetch()` → `newApi.get()`
- `oldApi.send()` → `newApi.post()`


## Completion
When grep returns no results, output:
<promise>COMPLETE</promise>

Pattern 3: Documentation

Section titled “Pattern 3: Documentation”
@.plans/progress.txt
run `git log --limit 10`


# Task: Add JSDoc Comments


1. Add JSDoc comments to all exported functions in src/.
2. Select a module that needs documentation. Only update a single module at a time.
3. Add JSDoc comments to all functions in that module.
4. Run typecheck and tests to verify correctness.
5. Reflect on what you have done and APPEND learning to .plans/progress.txt for future iterations.
6. Commit changes with a descriptive message.




## Guidelines
- Include @param and @returns
- Keep descriptions concise


## Progress
Track completed files in progress.txt


## Completion
When all exports are documented, output:
<promise>COMPLETE</promise>

Tips for Effective Prompts

Section titled “Tips for Effective Prompts”

Good prompt structure:

# Orientation
[Plans, history and learning e.g. @.plans/prd.json @.plans/progress.txt run `git log --limit 10`]


# Task
[What needs to be done]


# Guidelines
[How to do it well]


# Checking Progress
[How to see what's already done]


# Completion
[When to output <promise>COMPLETE</promise>]

Include these elements:

  1. Context — What’s the project? What’s the goal?
  2. Constraints — Style guides, patterns to follow
  3. Progress markers — How to check what’s done
  4. Completion signal — When to output the completion marker

Next Steps

Section titled “Next Steps”

Now that you’ve run your first loop: