---
title: "Glossary"
description: "**Agent** : An AI-powered CLI tool that executes tasks based on prompts. Ralph supports Claude, Gemini, and Q agents."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/glossary-1
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:24:56.082Z
license: CC-BY-4.0
attribution: "Glossary — Claudary (https://claudary.paisolsolutions.com/skills/glossary-1)"
---

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

## Overview

# 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

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/glossary-1) · https://claudary.paisolsolutions.com