ralph-workflow 0.7.18

# Ralph Unified Configuration File
# =================================
#
# This is the primary configuration file for Ralph.
# Location: ~/.config/ralph-workflow.toml
#
# Configuration priorities (highest to lowest):
# 1. CLI arguments (final override)
# 2. Environment variables (RALPH_*)
# 3. This config file
# 4. Built-in defaults

# =============================================================================
# GENERAL SETTINGS
# =============================================================================

[general]
# Verbosity level (0=quiet, 1=normal, 2=verbose, 3=full, 4=debug)
verbosity = 2

# Interactive mode - keep agent in foreground for real-time output
interactive = true

# Isolation mode - prevent context contamination between runs
# When enabled, NOTES.md and ISSUES.md are deleted at the start of each run
isolation_mode = true

# Auto-detect project stack (Rust, JavaScript, Python, etc.) for review guidelines
auto_detect_stack = true

# Enable checkpoint/resume functionality for interrupted runs
checkpoint_enabled = true

# Number of developer iterations (how many times the developer agent runs)
developer_iters = 5

# Number of review-fix cycles (0=skip review, 1=one cycle, 2=two cycles)
reviewer_reviews = 2

# Context levels for agents (0=minimal, 1=standard, 2=full)
developer_context = 1
reviewer_context = 0

# Review depth: standard (balanced), comprehensive (thorough),
# security (OWASP-focused), incremental (changed files only)
review_depth = "standard"

# Strict PROMPT.md validation
strict_validation = false

# Maximum continuation attempts when developer returns "partial" or "failed"
# Higher values allow more attempts to complete complex tasks within a single plan
# Default: 2 (initial attempt + 2 continuations = 3 total attempts per iteration)
# max_dev_continuations = 2

# Maximum additional commit residual retries after the initial residual-files check
# Default: 10 (carry residual files forward after pass 11)
# max_commit_residual_retries = 10

# Path to save the last prompt (relative to project root)
# prompt_path = ".agent/last_prompt.txt"

# Git user identity for commits (optional, falls back to git config)
# If not set, Ralph will use the standard git configuration from:
# - git config (user.name, user.email)
# - Environment variables: RALPH_GIT_USER_NAME, RALPH_GIT_USER_EMAIL
# - System username as a last resort
# git_user_name = "Your Name"
# git_user_email = "your.email@example.com"

# =============================================================================
# CCS ALIASES (Claude Code Switch)
# =============================================================================
#
# CCS allows you to manage multiple Claude profiles and providers.
# Define aliases here and use them as agents with "ccs/alias-name" syntax.
#
# Example usage in named chains:
#   [agent_chains]
#   developer = ["ccs/work", "claude", "codex"]
#
#   [agent_drains]
#   planning = "developer"
#   development = "developer"
#
# This uses your "work" CCS profile as the shared planning/development chain,
# falling back to Claude Code and then Codex if needed.
#
# Install CCS: https://github.com/kaitranntt/ccs

[ccs]
# Defaults applied to all CCS aliases unless overridden per-alias.
#
# If your CCS version doesn't support these Claude CLI flags, set them to "".
output_flag = "--output-format=stream-json"
verbose_flag = "--verbose"
#
# Print flag: Required for non-interactive mode.
# IMPORTANT: CCS treats `-p` / `--prompt` as its own delegation mode.
# Use Claude's long-form `--print` flag when invoking via the `ccs` wrapper.
print_flag = "--print"
#
# Session continuation flag: used for XSD retry loops to continue an existing conversation.
# The `{}` placeholder is replaced with the session ID.
session_flag = "--resume {}"
#
# YOLO (autonomous) mode: Skip permission/confirmation prompts for unattended operation.
# Ralph is designed for unattended automation, so this is enabled by default.
# Set to "" to disable and require confirmation for each action.
yolo_flag = "--dangerously-skip-permissions"
json_parser = "claude"
can_commit = true

[ccs_aliases]
# Personal profile - your default Claude account
# personal = "ccs personal"

# Work profile - work/enterprise Claude account
# work = "ccs work"

# Gemini profile - uses Google's Gemini models via CCS
# gemini = "ccs gemini"

# OpenRouter profile - uses OpenRouter for model access
# openrouter = "ccs openrouter"

# =============================================================================
# YOLO MODE AND UNATTENDED OPERATION
# =============================================================================
#
# Ralph is designed for UNATTENDED automation. Agents run with auto-approval
# (yolo mode) by default, meaning:
# - No prompts for file operations
# - No confirmation for tool calls
# - Fully autonomous code changes
#
# This is deliberate: permission is given upfront when you run Ralph.
#
# To DISABLE yolo mode (require confirmation for each action):
# - For CCS aliases (ccs/work, ccs/personal, etc.):
#   [ccs]
#   yolo_flag = ""  # Empty = disable yolo mode
#
# - For built-in non-CCS agents (claude, codex, aider, etc.):
#   [agents.claude]
#   yolo_flag = ""  # Empty = disable yolo mode for that agent
#
# Different agents use different yolo flags:
# - Claude/CCS: --dangerously-skip-permissions
# - Codex: --full-auto
# - Aider: --yes-always
# - Cline: -y
# - etc.
#
# The pipeline runner automatically adds the appropriate flag when building
# agent commands, ensuring consistent unattended behavior across all agents.

# =============================================================================
# CUSTOM AGENT DEFINITIONS (optional)
# =============================================================================
#
# You can define custom agents here. These are merged with built-in agents.
# Built-in agents (claude, codex, opencode, etc.) are defined in the binary.

# Example: Custom agent with specific model configuration
# [agents.my-claude-opus]
# cmd = "claude"
# # When running Claude directly (not via the `ccs` wrapper), `-p` and `--print` are both Claude CLI flags.
# # Prefer "--print" for consistency with unattended mode.
# print_flag = "--print"
# output_flag = "--output-format=stream-json"
# yolo_flag = "--dangerously-skip-permissions"
# verbose_flag = "--verbose"
# can_commit = true
# json_parser = "claude"
# model_flag = "--model claude-opus-4-20250514"

# Example: Local LLM agent
# [agents.local-llm]
# cmd = "ollama run codellama"
# output_flag = ""
# yolo_flag = ""
# verbose_flag = ""
# can_commit = false
# json_parser = "generic"

# =============================================================================
# AGENT CHAIN CONFIGURATION
# =============================================================================
#
# Define reusable named chains in [agent_chains], then bind the built-in runtime
# drains in [agent_drains]. Multiple drains can share the same named chain.
#
# Fallback triggers:
# - Rate limits (429 errors)
# - Authentication failures
# - Token/context exhaustion
# - Command not found
#
# You can use CCS aliases with "ccs/alias-name" syntax.
# Legacy [agent_chain] input is still accepted for compatibility, but the named
# chain + drain schema below is the canonical model.

[agent_chains]
# Shared development chain used by planning, development, and analysis drains.
developer = [
  "claude",      # Primary: Claude Code
  "codex",       # Fallback: OpenAI Codex
  "opencode",    # Fallback: OpenCode
]

# Shared review chain used by review, fix, and commit drains.
reviewer = [
  "codex",       # Primary: OpenAI Codex (different perspective)
  "claude",      # Fallback: Claude Code
]

[agent_drains]
planning = "developer"
development = "developer"
analysis = "developer"
review = "reviewer"
fix = "reviewer"
commit = "reviewer"

[agent_chain]
# Metadata-only compatibility section.
# Keep retry/backoff/provider fallback settings here when needed.

# Maximum retries per agent before trying the next one
max_retries = 3

# Delay between retries in milliseconds
retry_delay_ms = 1000

# =============================================================================
# PROVIDER-LEVEL FALLBACK (optional, for OpenCode)
# =============================================================================
#
# For agents that support multiple providers (like opencode), you can configure
# provider-level fallback. Ralph will try different models within the same agent
# before switching to the next agent in the chain.
#
# Uncomment to enable:
# [agent_chain.provider_fallback]
# opencode = ["-m opencode/glm-4.7-free", "-m opencode/claude-sonnet-4"]