Configuration

ralph uses a TOML configuration file located at .ralph/config.toml.

Configuration File

Run ralph init to create the configuration:

ralph init

Full Configuration Example

# AI adapter: claude, opencode, or gemini
adapter = "claude"

# Directory for plans, prompts, and progress
plansDir = ".plans"

# Maximum iterations before stopping
maxIterations = 10

# Enable verbose output
verbose = false

# Enable Terminal UI
tui = true

# Show token usage info
showUsage = false

# Lifecycle hooks (shell commands)
[hooks]
ralph_start = ""
ralph_loop_start = ""
ralph_loop_end = ""
ralph_complete = ""
ralph_max_iterations = ""

Configuration Options

Adapter

adapter = "claude"

The AI CLI tool to use. Options:

Adapter	Status	Description
`claude`	Complete	Anthropic’s Claude Code CLI
`opencode`	Complete	Open-source AI coding assistant
`gemini`	Under Development	Google’s Gemini CLI

Plans Directory

plansDir = ".plans"

Directory containing your PRD, prompt template, and progress file. Created by ralph init.

Max Iterations

maxIterations = 10

Safety limit on loop iterations. ralph stops when this limit is reached, even if the task isn’t complete.

Verbose Mode

verbose = false

Enable detailed output for debugging.

Terminal UI

tui = true

Enable the interactive terminal UI. Set to false for plain text output (useful in CI).

Show Usage

showUsage = false

Display token usage and cost information after each iteration.

Hooks

Hooks allow you to run shell commands at key points in the loop lifecycle.

[hooks]
ralph_start = "npm run lint:fix"
ralph_loop_start = ""
ralph_loop_end = "npm run format"
ralph_complete = "npm run notify"
ralph_max_iterations = ""

Available Hooks

Hook	Timing
`ralph_start`	Before the first iteration
`ralph_loop_start`	Before each iteration
`ralph_loop_end`	After each iteration
`ralph_complete`	When task completes successfully
`ralph_max_iterations`	When max iterations limit is reached

Configuration Precedence

Configuration is merged in this order (later overrides earlier):

Default values
User-level config (~/.ralph/config.toml)
Project-level config (.ralph/config.toml)
CLI options

Example:

# Config says maxIterations = 10
# This overrides to 5
ralph run --max-iterations 5

Project Structure

After running ralph init, your project will have:

project/
├── .ralph/
│   └── config.toml          # Configuration
└── .plans/
    ├── prd.json             # Product requirements (features to build)
    ├── PROMPT.md            # System prompt for the AI
    └── progress.txt         # Learning log across iterations

The AI reads and modifies files in .plans/ during execution, persisting state between context resets.