DOCSEARCHbyAlgolia
Submit Docs

Ralph AI Agent Loop

repository·main·Indexed 43 days ago

https://github.com/pageai-pro/ralph-loop

A long-running AI agent loop designed to automate software development tasks. Ralph iteratively executes tasks from a generated list, runs tests, and commits changes within secure Docker sandboxes. It supports multiple agentic CLIs including Claude, Codex, Copilot, Cursor, Gemini, and Opencode, and utilizes a system of reusable skills and a `.agent/` configuration directory to manage the development lifecycle.

Tokens
5.2K
Snippets
13
Records
19
Agent score
6%

What's inside Ralph

  1. Understand Ralph's status communication and exit codes

    main

    Ralph uses semantic Promise Tags to communicate the status of an agentic loop. These tags are used to signal whether the agent is finished, needs human intervention, or requires a decision.

    Promise Tags:

    • <promise>COMPLETE</promise>: All tasks finished successfully.
    • <promise>BLOCKED:reason</promise>: Agent needs human help.
    • <promise>DECIDE:question</promise>: Agent needs a decision.

    Exit Codes: Ralph returns specific exit codes based on the loop outcome:

    • 0: COMPLETE - All tasks finished.
    • 1: MAX_ITERATIONS - Reached the iteration limit.
    • 2: BLOCKED - Needs human help.
    • 3: DECIDE - Needs human decision.

  2. Explore the .agent directory structure

    main

    The .agent/ directory is the central configuration and state repository for the Ralph loop. It contains the prompts, task definitions, and logs used by the agent.

    Directory Layout:

    • .agent/PROMPT.md: The prompt sent to the Agent during each iteration.
    • .agent/tasks.json: The required task lookup table.
    • .agent/tasks/: Contains individual task specifications (e.g., TASK-{ID}.json).
    • .agent/prd/: Contains the Product Requirements Document (PRD.md) and a short project overview (SUMMARY.md).
    • .agent/logs/: Contains the progress log (LOG.md), which is auto-created.
    • .agent/history/: Stores iteration output logs.
    • .agent/skills/: The source of truth for reusable agent capabilities (skills).

  3. Steer the agent using STEERING.md

    main

    If the agent encounters a blocker or needs to prioritize specific work, you can intervene while the loop is running.

    Edit the .agent/STEERING.md file to add instructions for critical work. During the next iteration, the agent will check this file; if it finds critical work, it will skip current tasks to address the steering requirements first.

  4. How the Ralph Loop works

    main

    The Ralph loop is an iterative process that automates software development. In each iteration, the system:

    1. Identifies Work: Finds the highest-priority incomplete task from .agent/tasks.json.
    2. Executes Steps: Works through the specific steps defined in .agent/tasks/TASK-{ID}.json.
    3. Verifies: Runs tests, linting, and type checking.
    4. Finalizes: Completes the task, captures a screenshot, updates the task status, and commits the changes.
    5. Repeats: Continues until all tasks pass or the maximum iteration limit is reached.

  5. Use and manage agent skills

    main

    Skills are reusable agent capabilities providing specialized knowledge or workflows. The canonical source for all skills is .agent/skills/. To ensure compatibility with various AI CLIs (like Claude, Cursor, or Codex), the contents of .agent/skills/ are symlinked to several other directories.

    Available Skills include:

    • agent-browser: Browser automation.
    • component-refactoring: React component refactoring patterns.
    • e2e-tester: End-to-end testing workflows.
    • frontend-code-review: Code quality and performance guidelines.
    • frontend-testing: Unit and integration testing patterns.
    • mysql / postgres: Database schema, indexing, and optimization.
    • prd-creator: Creating PRDs and task breakdowns.
    • shadcn: Managing shadcn components and UI.
    • skill-creator: Creating new skills.
    • vercel-react-best-practices: React/Next.js performance patterns.
    • vitest-best-practices: Vitest structure and testing patterns.
    • web-design-guidelines: UI/UX design principles.

    Updating the Project via Skills: You can expand the project scope by instructing the agent to use the prd-creator skill to update the PRD and task list. For example: I would like to expand the PRD. Use the prd-creator skill to create these tasks: [list of tasks]

  6. Configure authentication via environment variables

    main

    Because Docker Sandboxes may fail to persist OAuth tokens (e.g., when running /login inside a sandbox shell), the recommended way to handle authentication is by passing API keys through environment variables.

    Important: Environment variables are only picked up at the time of sandbox creation. If you need to add or change an API key, you must delete the existing sandbox first.

    Steps to set up authentication:

    1. Delete the existing sandbox.
    2. Export the required API keys in your host shell (e.g., export ANTHROPIC_API_KEY=your-key). To make these permanent, add them to your .bashrc or .zshrc.
    3. Recreate the sandbox by running ./ralph.sh --login.

    Common Keys:

    • Anthropic: ANTHROPIC_API_KEY
    • OpenAI: OPENAI_API_KEY
    • Cursor: CURSOR_API_KEY
    # 1. Delete existing sandbox (manual step)

# 2. Export keys in your host terminal
export ANTHROPIC_API_KEY=your-anthropic-api-key
export OPENAI_API_KEY=your-openai-api-key

# 3. Recreate the sandbox to pick up the new env vars
./ralph.sh --login

  8. Inspect and debug sandboxes using sbx

    main

    You can interact with the Docker sandboxes used by Ralph to inspect the environment, install packages, or run commands manually.

    1. List active sandboxes: Use sbx ls to find the name of the sandbox running your agent (e.g., ralph-claude-my-app-a1b2c3d4).
    2. Enter a sandbox: Use sbx exec -it <sandbox-name> bash to open an interactive shell inside the container.
    3. Run agent CLIs manually: Once inside the sandbox, navigate to your project directory (which shares the same path as your host machine) and run your agent CLI (e.g., claude, codex, copilot, cursor, gemini, or opencode).

    Note: Re-running ./ralph.sh is safe; it will either create a new sandbox or reattach to an existing one depending on the name provided.

    # List sandboxes
sbx ls

# Enter a specific sandbox
sbx exec -it ralph-claude-my-app-a1b2c3d4 bash

# Inside the sandbox, navigate to your project and run the agent
cd /Users/your-username/Documents/your-project
claude

  9. Create a PRD and task list using prd-creator

    main

    Before running the loop, you must generate a Product Requirements Document (PRD) and a task list.

    1. Open your preferred agentic AI (e.g., Claude Code, Cursor) and switch to plan mode.
    2. Use the prd-creator skill by prompting the agent with your requirements.
    3. Include details such as desired libraries, frameworks, environment variables (e.g., SUPABASE_URL), and user flows.
    4. Verify the generated PRD and tasks. It is highly recommended to review each task individually before starting the loop.
    Use the prd-creator skill to help me create a PRD and task list for the below requirements.

An app is already set up with React, Tailwind CSS and TypeScript.

Requirements:

- A SaaS product that helps users manage their finances.
- ...
- Use the shadcn/ui library for components.
- Integrate with Stripe for payments.
- Use Supabase for database.
- You can find env variables in the .env.example file: SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, etc. are available in the runtime.

  10. Set up the agent inside Docker Sandboxes

    main

    Ralph operates within Docker Sandboxes to provide a secure, isolated environment.

    1. Authentication

    Authenticate your chosen agent (Claude is the default) using the --login flag. This opens the agent inside the correctly named sandbox.

    2. Sandbox Naming

    Sandboxes are named following the pattern: ralph-<agent>-<current-dir>-<hash8> (e.g., ralph-claude-my-app-a1b2c3d4).

    3. Port Publishing

    To allow the agent to access your local development server, publish the port using the --ports command. This uses the port captured from your dev-server URL during installation.

    4. Permissions

    When prompted, answer "Yes" to Bypass Permissions mode to allow the agent to operate effectively within the sandbox.

    # Login to the default agent
./ralph.sh --login

# Login to a specific agent (e.g., codex)
./ralph.sh --login --agent codex

# Print the sandbox name without starting the loop
./ralph.sh --print-name
./ralph.sh --print-name --agent cursor

# Publish the dev server port to the sandbox
./ralph.sh --ports
./ralph.sh --ports --agent codex

  11. Manage Docker Sandboxes for Ralph

    main

    Ralph runs coding agents in isolated Docker Sandboxes using the sbx CLI. Each run uses a deterministic sandbox name: ralph-<agent>-<current-dir>-<hash8>. This allows different agents to have separate sandboxes for the same project.

    Useful Commands:

    • ./ralph.sh --login: Authenticate inside the specific named sandbox for the current project.
    • ./ralph.sh --print-name: Print the deterministic sandbox name (useful for debugging).

  12. Install testing dependencies for Ralph

    main

    To allow the agent to verify its own implementations, you must install an end-to-end test framework and a unit test framework. Use the following commands to set up Playwright and Vitest:

    npm i @playwright/test vitest jsdom typescript eslint prettier -D

# If using React, also recommend installing:
npm i @vitejs/plugin-react @testing-library/dom @testing-library/jest-dom @testing-library/react @testing-library/user-event -D