How do I run ralph wiggum with cursor-agent cli?

Author’s note: https://www.bryanwhiting.com/ai/ralph/

Introduction To Ralph Wiggum

The ‘Ralph Wiggum’ technique is an agent pattern for autonomous AI development, popularized in late 2025, designed to execute tasks in a persistent loop until a defined goal is achieved. Named after the Simpsons character known for his persistence, this method involves an AI agent, such as the Cursor Agent, repeatedly working on a problem until it is solved. The process is typically driven by a task list, often a markdown file (e.g., RALPH_TASK.md) containing a series of checkboxes ([ ]). The agent’s goal is to iterate through the tasks, implementing solutions and marking the checkboxes as complete ([x]). The loop continues until all checkboxes are checked or until a predefined guardrail, such as a maximum number of iterations or a time limit, is met. This pattern allows for a controlled, autonomous workflow where the agent can plan, execute, and verify its work cycle after cycle. Community wrappers and scripts have been developed to facilitate this process, adding features like context rotation to manage token limits, progress tracking, and rate limiting.

Cursor Agent Cli Prerequisites

To run the ‘Ralph Wiggum’ technique with the Cursor Agent, several prerequisites must be met. The primary requirement is the installation of the Cursor Agent CLI. This can be accomplished using a one-line installer command provided in the official documentation and community guides: curl https://cursor.com/install -fsS | bash. After running this command, it is crucial to verify that the installation was successful and that the cursor-agent executable is available in the system’s PATH. The documentation suggests that the installation path ~/.local/bin may need to be manually added to your PATH. A simple way to check is by running a command like which cursor-agent. Another fundamental prerequisite is having a Git-initialized repository, as the agent operates within the context of a version-controlled project. Additionally, while not strictly necessary, several optional tools are recommended for an enhanced experience. These include gum for a friendlier command-line user interface, and tools like tmux and jq for monitoring the agent’s progress and parsing JSON output, respectively.

Implementation Comparison

Workflow And Best Practices

The typical user workflow for using a Ralph Wiggum agent with the Cursor Agent CLI involves setting up the environment, defining a clear task list, and initiating a controlled loop that runs until the task is complete. The process begins with ensuring prerequisites are met, which include having a Git-initialized repository and the Cursor CLI (cursor-agent) installed and available on the system’s PATH. The core of the workflow is creating a markdown file, conventionally named RALPH_TASK.md, which contains a checklist of tasks using markdown’s [ ] syntax. This file serves as the primary instruction set and progress tracker for the agent. Once the task file is prepared, the user can initiate the agent loop. There are two primary methods for this: using a dedicated community wrapper script like ‘ralph-wiggum-cursor’, or building a custom ‘do-it-yourself’ loop using shell scripting and Cursor CLI primitives. The wrapper script simplifies the process by providing interactive setup, automatic progress tracking, and context rotation. The user runs a setup script, selects options like the AI model, and the wrapper handles the repeated calls to cursor-agent. For monitoring, the wrapper provides real-time logs, and some variants offer a tmux dashboard. The loop automatically terminates when all checkboxes in RALPH_TASK.md are marked as complete ([x]) or a predefined guardrail, such as a maximum iteration count, is reached. Best practices for achieving good results emphasize authoring a high-quality RALPH_TASK.md file. Tasks should be broken down into small, specific, objective, and testable items. Vague instructions are less effective. Additionally, it is recommended to use Cursor’s rules system by creating a .cursor/rules directory to provide the agent with specific context and constraints on its behavior. Implementing guardrails, such as setting a MAX_ITERS environment variable or other completion triggers, is crucial to prevent infinite loops and manage costs.

Bottom Line Summary

To run a “Ralph Wiggum” agent with the Cursor CLI, the process involves four main steps. First, install the cursor-agent and verify that it runs correctly on your system.¹² Second, create a RALPH_TASK.md file in your project’s repository, outlining the tasks to be completed using a checklist format with [ ] for each item.³ Third, you have two primary options: either use a pre-built community wrapper like ralph-wiggum-cursor which provides a controlled loop with features like context rotation, or script your own simple loop using the cursor-agent’s native interactive or non-interactive modes.³⁴ Finally, execute the chosen script or wrapper and allow it to iterate through the tasks, making changes and marking checkboxes as [x], until the entire checklist is completed or a predefined guardrail, such as a maximum iteration count, is triggered.³

Final Output Report

How to Run “Ralph Wiggum” with the Cursor Agent CLI

Ralph Wiggum (the loop-until-done agent pattern popularized in late 2025) can be run against your local repo using the Cursor Agent CLI.⁵ Below is a practical guide: install prerequisites, scaffold a Ralph task file, and start a controlled loop that repeatedly invokes cursor-agent until your checklist is complete or guardrails trigger an exit.

What You’ll Build

• A Ralph loop driven by cursor-agent that iterates on a task list (checkboxes) until done.⁵³
• Optional monitoring and guardrails (rate limiting, iteration caps, context rotation).⁵³

Prerequisites

• A Git-initialized repository.⁶
• Cursor CLI (cursor-agent) installed and on PATH.¹⁴²
• Optional: tmux and jq for monitoring/json; gum for a friendlier UI.³

Install Cursor Agent CLI

• One-line installer:²

  curl https://cursor.com/install -fsS | bash

• Verify and learn core usage from the official docs (interactive and non-interactive modes, sessions, rules, MCP).¹⁴

Two Ways to Run Ralph with Cursor CLI

Option A: Use the dedicated “Ralph Wiggum for Cursor” scripts

A community implementation provides shell scripts that wrap cursor-agent with a Ralph loop (task file, iterations, context rotation, progress parsing).³

1. Install Ralph (one-time) and project setup

• The repo exposes commands such as ralph-setup.sh, ralph-loop.sh, ralph-once.sh.³
• Prerequisites table includes: git repo, cursor-agent in PATH, optional gum.³

2. Define your task (checkbox list)

• Create RALPH_TASK.md with [ ] items; the loop tracks completion by counting unchecked boxes.³

3. Start the loop

• Run the primary script (interactive) to choose model/options and start invoking cursor-agent repeatedly until completion or max iterations.³

What the wrapper does

• Calls cursor-agent with your prompt/context, monitors token usage and rotates context around 70–80k tokens, and repeats until all boxes are checked.³

Option B: Roll your own loop using Cursor CLI primitives

If you prefer minimal dependencies, you can script a simple loop around cursor-agent using official CLI features (interactive or non-interactive, sessions, rules, MCP).¹⁴

Basic non-interactive skeleton

set -euo pipefail

# Ensure you’re in a git repo with a RALPH_TASK.md checklist
# Exit once all [ ] checkboxes are turned into [x]

MAX_ITERS=${MAX_ITERS:-20}
THREAD_ID=""  # optionally persist with --resume

for ((i=1; i<=MAX_ITERS; i++)); do
  echo "--- Ralph Iteration $i ---"
  # Feed task file to the agent and print a short plan first
  cursor-agent --print --output-format text \
    -m auto \
    -p "Read RALPH_TASK.md and propose the next concrete step; then implement it. Stop to let me review. Do not over-edit unrelated files." \
    @RALPH_TASK.md

  # Let the agent apply changes interactively (approve commands, review diff)
  cursor-agent \
    -m auto \
    -p "Implement the approved next step, update RALPH_TASK.md, and mark completed items [x]." \
    @RALPH_TASK.md

  # Check if any checkboxes remain
  if ! grep -q "\[ \]" RALPH_TASK.md; then
    echo "All tasks complete. Exiting."; break
  fi

  # Optional: sleep, rotate session, or compress context between loops
  # cursor-agent resume / ls are available for session management
  sleep 5
done

Notes

• Use —print for non-interactive plans and a second call for edits, mirroring “plan + apply” cycles.⁴
• You can persist context with resume/ls, and scope context with @file notation and rules.⁴
• For larger repos, add .cursor/rules and MCP servers for tool augmentation.⁴

Practical Setup with the Community Wrapper (Option A)

Install and run

# clone the wrapper repo (one-time)
git clone https://github.com/agrimsingh/ralph-wiggum-cursor
cd ralph-wiggum-cursor

# optional UI helpers
eval "$(command -v brew >/dev/null && echo 'brew install gum')" || true

# initialize in your target project repo (separate shell)
cd /path/to/your/project
bash /path/to/ralph-wiggum-cursor/ralph-setup.sh    # interactive setup + run
# or
bash /path/to/ralph-wiggum-cursor/ralph-once.sh     # single iteration test
bash /path/to/ralph-wiggum-cursor/ralph-loop.sh     # scriptable loop

• The wrapper checks prerequisites (git, cursor-agent) and guides model selection; without gum, it falls back to numeric prompts.³
• It reads RALPH_TASK.md, runs cursor-agent in cycles, and rotates context as tokens grow; exits when all [ ] are [x] or a cap is reached.³

Authoring RALPH_TASK.md

# Build and Ship MVP

- [ ] Scaffold API server and health endpoint
- [ ] Implement /users CRUD with SQLite
- [ ] Add auth middleware and session handling
- [ ] Write smoke tests; document run commands
- [ ] Prepare Dockerfile and deploy to Fly.io

• Keep items small, objective, and testable; Ralph loops can also incorporate guardrails like max-iterations or completion-trigger strings.⁵⁷

How Ralph Maps onto Cursor CLI

• Cursor CLI supports interactive and non-interactive agent runs, plus sessions, rules, and MCP—everything you need for a loop controller.¹⁴
• Ralph wrappers add: loop control, progress tracking, context rotation, rate/circuit breakers, and dashboards (tmux).³
• Cursor advertises frontier model access and a simple installer, making it easy to drop into CI or terminal workflows.²⁸⁹

Comparison: DIY vs Wrapper

Sources indicate the Cursor ecosystem has embraced headless/CLI agent runs and community Ralph tooling, so both paths are viable.³¹⁴⁸

Tips and Limits

• Keep RALPH_TASK.md crisp; agents work best when instructions are specific with clear success criteria.⁴
• Use rules in .cursor/rules and an AGENTS.md/CLAUDE.md file to constrain behavior.⁴
• Cursor Agent prompts for command approval; in non-interactive (—print), it prints responses directly (full write access when non-interactive).⁴
• Cursor community mentions time caps on single requests; loops should incorporate iteration or time limits.¹⁰

Bottom Line

• Install cursor-agent; verify it runs.¹²
• Author RALPH_TASK.md with [ ] checkboxes.³
• Either use a community wrapper (ralph-wiggum-cursor) or script a simple loop around cursor-agent’s interactive/non-interactive modes.³⁴
• Iterate until all boxes are checked or guardrails fire.³

References