Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• install.sh
• setup.sh
• README.md
• create_files.sh
• ralph_import.sh
• CONTRIBUTING.md

This guide provides instructions for installing the Ralph for Claude Code system and initializing new projects for autonomous AI development. The process is divided into two main phases: a one-time global installation of the Ralph command-line tools, followed by a per-project setup to configure the development environment for the AI agent.

The primary goal is to set up an environment where the ralph command can run an autonomous loop, iteratively using Claude Code to work on a software project based on a set of instructions and specifications. This setup enables continuous development cycles with features like intelligent exit detection, rate limiting, and live monitoring.

Sources: README.md:100-107, CONTRIBUTING.md:23-37

System Requirements

Before starting, ensure your system has the following dependencies installed.

Dependency	Purpose	Source
Bash 4.0+	Script execution	CONTRIBUTING.md:26
jq	JSON processing for status tracking	CONTRIBUTING.md:27
git	Version control for projects	CONTRIBUTING.md:28
tmux	Terminal multiplexer for integrated monitoring	README.md:403
Node.js 18+	For running the test suite via npm	CONTRIBUTING.md:30
Claude Code CLI	The AI execution engine	README.md:402

Sources: README.md:400-406, CONTRIBUTING.md:24-30

Phase 1: One-Time Installation

The first step is to install the Ralph scripts globally on your system. This process only needs to be done once. The install.sh script handles the creation of necessary directories and makes the Ralph commands available in your system's PATH.

Sources: README.md:113-122

Installation Process

The installation script performs the following actions:

1. Creates directories ~/.local/bin and ~/.ralph.
2. Copies the core scripts (ralph_loop.sh, ralph_monitor.sh, etc.) to ~/.ralph/.
3. Copies templates and library files to subdirectories within ~/.ralph/.
4. Creates symbolic links in ~/.local/bin for the main commands, making them globally accessible.
5. Checks for required dependencies like git and jq.

This diagram illustrates the flow of the install.sh script.

To install, clone the repository and run the script:

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

This makes the ralph, ralph-monitor, ralph-setup, and ralph-import commands available system-wide.

Sources: README.md:116-118

Phase 2: Project Initialization

Once Ralph is installed, you can create new projects for it to work on. There are two primary methods for initializing a project.

Sources: README.md:124-126

Option A: Import from an Existing Document

This is the recommended method if you have an existing Product Requirements Document (PRD), specification, or list of requirements. The ralph-import command uses Claude to intelligently convert your document into the structured files Ralph needs.

The process is as follows:

1. The user runs ralph-import <source-file> [project-name].
2. The script calls ralph-setup to create a new project directory.
3. The source PRD file is copied into the new project.
4. A special prompt is constructed, asking Claude to convert the PRD into PROMPT.md, @fix_plan.md, and specs/requirements.md.
5. The claude CLI is executed with this prompt.
6. The generated files are saved in the project directory, ready for the autonomous loop.

Sources: ralph_import.sh:310-357, README.md:154-160

This sequence diagram shows the ralph-import workflow.

Option B: Manual Project Setup

If you are starting from scratch, you can use ralph-setup to create a blank project with the standard directory structure.

# Create a blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project

This command, which is a global alias for setup.sh, creates the following structure:

my-awesome-project/
├── PROMPT.md           # Main development instructions for Ralph
├── @fix_plan.md        # Prioritized task list
├── @AGENT.md           # Build and run instructions
├── specs/              # Project specifications
│   └── stdlib/
├── src/                # Source code implementation
├── examples/           # Usage examples
├── logs/               # Ralph execution logs
└── docs/generated/     # Auto-generated documentation

After creation, you must manually edit PROMPT.md, specs/, and @fix_plan.md with your project's goals and tasks.

Sources: README.md:143-152, 431-443, setup.sh:8-20, create_files.sh:418-429

This diagram shows the file structure created by setup.sh.

Phase 3: Running the Autonomous Loop

With a project initialized, you can start the autonomous development loop. The recommended way is to use the integrated tmux monitoring session.

# Navigate to your project directory
cd my-awesome-project

# Start with integrated monitoring
ralph --monitor

This command starts the main ralph_loop.sh script and the ralph_monitor.sh dashboard in a split tmux window. The loop will continuously execute Claude Code based on PROMPT.md and @fix_plan.md, while the monitor provides real-time status updates.

Sources: README.md:150-152, 411-414, create_files.sh:371-374

The following table summarizes the key commands available after installation.

Command	Description	Source
ralph	Starts the main autonomous development loop.	create_files.sh:300-302
ralph --monitor	Starts the loop and a live monitoring dashboard in a tmux session.	README.md:150
ralph-monitor	Starts only the live monitoring dashboard in a separate terminal.	create_files.sh:371-374
ralph-setup	Creates a new, blank Ralph project structure.	setup.sh:4-6
ralph-import	Converts an existing PRD or spec file into a Ralph project.	ralph_import.sh:207-209
ralph --status	Shows the current status of the Ralph loop from the status.json file.	create_files.sh:343-351

Sources: README.md:478-500, create_files.sh, setup.sh, ralph_import.sh

This guide covers the essential steps to get the Ralph for Claude Code system operational. After completing these steps, the AI agent is ready to begin development work on your project autonomously. For more advanced configuration and contribution guidelines, refer to the CONTRIBUTING.md and README.md files.