Tutorial: Your First Autonomous Project
Relevant source files
The following files were used as context for generating this wiki page:This tutorial guides you through setting up and running your first autonomous development project using Ralph. Ralph is an implementation of a technique for Claude Code that enables continuous autonomous development cycles. It iteratively improves your project based on your instructions until the objectives are met, with built-in safeguards to manage API usage and prevent infinite loops.
This guide covers the one-time installation of Ralph, project initialization, configuration, and execution. By the end, you will have a new project managed by the Ralph autonomous agent, ready to start development. For more details on the project's architecture and contribution guidelines, see the Technical Specifications (CLAUDE.md) and Contributing Guide.
Sources: README.md:12-15, CLAUDE.md:5-8
Overall Workflow
The process involves a one-time installation followed by a per-project setup and execution cycle.
This diagram shows the high-level workflow for using Ralph.
Sources: README.md:144-149, README.md:160-182
Phase 1: Installation (One-Time)
Before using Ralph, you must install it globally on your system. This process copies the necessary scripts and templates to your user's local directory, making the ralph, ralph-setup, ralph-import, and ralph-monitor commands available system-wide.
Prerequisites
Ensure the following tools are installed on your system:
| Tool | Purpose | Source |
|---|---|---|
| Bash 4.0+ | Script execution | CONTRIBUTING.md:21 |
| Claude Code CLI | The AI execution engine | README.md:310 |
| tmux | Integrated monitoring (recommended) | README.md:311 |
| jq | JSON processing for status tracking | README.md:312 |
| git | Version control for projects | README.md:313 |
Installation Steps
- Clone the repository:
git clone https://github.com/Alonso-pixel/ralph-claude-code.git cd ralph-claude-code - Run the installation script:
./install.sh
This script installs the Ralph commands to ~/.local/bin/ and the core scripts and templates to ~/.ralph/. You only need to perform this installation once per system.
Sources: README.md:152-156, CLAUDE.md:118-123
Phase 2: Project Initialization
With Ralph installed, you can now create projects for the autonomous agent to work on. There are two primary methods for initializing a project.
Option A: Manual Setup
This option creates a blank but structured project, which you then configure manually. Use the ralph-setup command (which is a link to the setup.sh script).
ralph-setup my-awesome-project
cd my-awesome-project
This command creates a new directory with a standard structure, initializes a Git repository, and copies over the necessary template files for you to edit.
Sources: README.md:174-182, create_files.sh:503-520
The following diagram illustrates the project structure created by ralph-setup.
Sources: README.md:331-343, create_files.sh:506-511
Option B: Import from Existing Document
If you have an existing Product Requirements Document (PRD), specification, or design document, you can use ralph-import to automatically convert it into a Ralph project structure.
ralph-import my-requirements.md my-project
cd my-project
The ralph-import script uses the Claude Code CLI to analyze your document and generate the PROMPT.md, @fix_plan.md, and specs/requirements.md files. It supports various formats, including Markdown, text, JSON, DOCX, and PDF.
Sources: README.md:161-169, ralph_import.sh:1-3
This flowchart shows the process ralph-import follows.
Sources: ralph_import.sh:400-488
Phase 3: Configuration
After initializing your project, you must configure it by editing the key control files. These files guide the autonomous agent's behavior.
| File | Purpose |
|---|---|
PROMPT.md | Contains the main development instructions, objectives, and principles for the AI agent. This is the primary driver for each development loop. |
@fix_plan.md | A prioritized to-do list. The agent will work through these tasks, starting with "High Priority". You should break down your project into actionable items here. |
@AGENT.md | Contains build, test, and run instructions for the project. The agent refers to and updates this file to understand how to interact with the codebase. |
specs/ | A directory to hold detailed technical specifications, data models, or other requirement documents that provide deeper context for the agent. |
Sources: README.md:331-343, create_files.sh:563-657, templates/PROMPT.md:4-17, templates/AGENT.md:3-23
Phase 4: Execution and Monitoring
Once your project is configured, you can start the autonomous development loop.
Starting the Loop
The recommended way to run Ralph is with the integrated monitor, which uses tmux to display the live loop and a monitoring dashboard in a split-screen view.
ralph --monitor
Alternatively, you can run the loop and monitor in separate terminals:
- Terminal 1:
ralph - Terminal 2:
ralph-monitor
Sources: README.md:185-191, create_files.sh:417-420
The Development Loop
The ralph_loop.sh script executes a continuous cycle. The following sequence diagram illustrates a single iteration of the loop.
This diagram shows how ralph_loop.sh checks for rate limits and exit conditions, executes the Claude Code CLI with the project prompt, and logs the results before repeating the cycle.
Sources: create_files.sh:28-403
Monitoring
The ralph_monitor.sh script provides a live dashboard showing:
- Current loop count and status (
running,completed,error). - API calls made in the current hour versus the configured limit.
- Recent activity from the
logs/ralph.logfile. - A countdown timer for when the API rate limit will reset.
This allows you to observe the agent's progress in real-time without manually checking log files.
Sources: create_files.sh:427-500, README.md:386-392
Summary
You have now successfully installed Ralph, created and configured your first autonomous project, and launched the development loop. The agent will now begin working on the tasks defined in @fix_plan.md, following the instructions in PROMPT.md. You can monitor its progress using the ralph-monitor dashboard and review the detailed outputs in the logs/ directory. From here, you can let the agent work, or you can refine the prompts and specifications to guide its development.