Glossary

A

Agent

An AI-powered CLI tool that executes tasks based on prompts. Ralph supports Claude, Gemini, and Q agents.

Agent Manager

Component that detects, selects, and manages AI agents, including automatic fallback when preferred agents are unavailable.

Archive

Storage of historical prompts and iterations in .agent/prompts/ directory for debugging and analysis.

Auto-detection

Ralph's ability to automatically discover which AI agents are installed and available on the system.

C

Checkpoint

A Git commit created at regular intervals to save progress and enable recovery. Default interval is every 5 iterations.

Claude

Anthropic's AI assistant, accessible via Claude Code CLI. Known for high context window (200K tokens) and code generation capabilities.

CLI

Command Line Interface - the primary way to interact with Ralph Orchestrator through terminal commands.

Config

Configuration settings stored in ralph.json or passed via command line arguments and environment variables.

Context Window

The maximum amount of text/tokens an AI agent can process in a single request. Varies by agent (Claude: 200K, Gemini: 32K, Q: 8K).

Convergence

The process of iterations gradually approaching task completion through successive improvements.

Completion Marker

A special checkbox pattern (- [x] TASK_COMPLETE) in the prompt file that signals task completion. When the orchestrator detects this marker, it immediately exits the loop.

D

Dry Run

Test mode that simulates execution without actually running AI agents. Useful for testing configuration and setup.

Deterministic Failure

The philosophy that it's better to fail predictably than succeed unpredictably - core to the Ralph Wiggum technique.

E

Exponential Backoff

Retry strategy where wait time doubles after each failure (2, 4, 8, 16 seconds) to handle transient errors.

Execution Cycle

One complete iteration of reading prompt, executing agent, checking completion, and updating state.

G

Gemini

Google's AI model, accessible via Gemini CLI. Balanced context window (32K tokens) and capabilities.

Git Integration

Ralph's use of Git for checkpointing, history tracking, and recovery from failed states.

I

Iteration

One complete cycle of the Ralph loop - executing an agent with the current prompt and processing results.

Iteration Limit

Maximum number of iterations before Ralph stops. Default is 100, configurable via max_iterations.

L

Loop

The core Ralph pattern - continuously running an AI agent until task completion or limits are reached.

Loop Detection

Safety feature that detects when an agent is producing repetitive outputs. Uses fuzzy string matching (rapidfuzz) with a 90% similarity threshold to compare recent outputs and prevent infinite loops.

M

Metrics

Performance and execution data collected in .agent/metrics/ including timing, errors, and resource usage.

MkDocs

Static site generator used for Ralph's documentation, configured in mkdocs.yml.

O

Orchestrator

The main component that manages the execution loop, agent interaction, and state management.

P

Prompt

The task description file (usually PROMPT.md) that tells the AI agent what to accomplish.

Prompt Archive

Historical storage of all prompt iterations in .agent/prompts/ for debugging and analysis.

Plugin

Extension mechanism for adding custom agents or commands to Ralph.

Q

Q Chat

An AI assistant accessible via Q CLI. Smaller context window (8K tokens) but fast execution.

R

Ralph Wiggum Technique

The software engineering pattern of putting AI agents in a loop until the task is done, created by Geoffrey Huntley.

Recovery

Process of resuming execution from a saved state or Git checkpoint after failure or interruption.

Retry Logic

Automatic retry mechanism with exponential backoff for handling transient failures.

Runtime Limit

Maximum execution time in seconds before Ralph stops. Default is 14400 (4 hours).

S

State

Current execution status including iteration count, errors, and metrics, saved in .agent/metrics/state_latest.json.

State Manager

Component responsible for saving, loading, and updating execution state across iterations.

Success Criteria

The measurable objectives defined in PROMPT.md that guide the orchestrator towards completion.

T

Task

The work to be accomplished, described in PROMPT.md with requirements and success criteria.

Task Complete

State when the orchestrator reaches its maximum iterations, runtime, or cost limits, having worked towards the defined objectives.

Timeout

Maximum time allowed for a single agent execution. Default is 300 seconds (5 minutes) per iteration.

Token

Unit of text processed by AI models. Roughly 4 characters = 1 token.

U

Unpossible

Reference to Ralph Wiggum's quote, embodying the philosophy of achieving the seemingly impossible through persistence.

V

Verbose Mode

Detailed logging mode enabled with --verbose flag for debugging and monitoring.

W

Working Directory

The directory where Ralph executes, containing PROMPT.md and project files. Defaults to current directory.

Workspace

The .agent/ directory containing Ralph's operational data including metrics, checkpoints, and archives.

Technical Terms

API

Application Programming Interface - the interface through which Ralph communicates with AI services.

JSON

JavaScript Object Notation - format used for configuration files and state storage.

Subprocess

Separate process spawned to execute AI agents, providing isolation and timeout control.

YAML

YAML Ain't Markup Language - human-readable data format used for some configuration files.

File Formats

.md

Markdown files used for prompts and documentation.

.json

JSON files used for configuration and state storage.

.yaml/.yml

YAML files used for configuration (e.g., mkdocs.yml).

.log

Log files containing execution history and debugging information.

Directory Structure

.agent/

Ralph's workspace directory containing all operational data.

.agent/metrics/

Storage for execution metrics and state files.

.agent/prompts/

Archive of historical prompt iterations.

.agent/checkpoints/

Markers for Git checkpoints created during execution.

.agent/logs/

Execution logs for debugging and analysis.

.agent/plans/

Agent planning documents and long-term strategies.

Command Reference

ralph run

Execute the orchestrator with current configuration.

ralph init

Initialize a new Ralph project with default structure.

ralph status

Check current execution status and metrics.

ralph clean

Clean workspace and reset state.

ralph agents

List available AI agents on the system.

Environment Variables

RALPH_AGENT

Override default agent selection.

RALPH_MAX_ITERATIONS

Set maximum iteration limit.

RALPH_MAX_RUNTIME

Set maximum runtime in seconds.

RALPH_VERBOSE

Enable verbose logging (true/false).

RALPH_DRY_RUN

Enable dry run mode (true/false).

Exit Codes

0: Success - task completed successfully

1: General failure - check logs for details

130: Interrupted - user pressed Ctrl+C

137: Killed - process terminated (often memory issues)

124: Timeout - execution time exceeded