Configuration

Complete reference for Ralph's YAML configuration.

Configuration File

Ralph composes configuration from up to three layers:

1. ~/.ralph/config.yml when present — user-level defaults loaded automatically
2. ralph.yml in the current workspace (or $RALPH_CONFIG / -c <file>) — project-level overrides
3. -c core.field=value overrides — applied last

Project config overlays on top of the user config via deep merge. Mappings are merged recursively and scalar values or arrays from the project config replace the user-level value.

# Use the workspace config (and automatically merge ~/.ralph/config.yml if present)
ralph run

# Override the project config path
RALPH_CONFIG=/path/to/config.yml ralph run ...
ralph run -c custom-config.yml

User-level config (~/.ralph/config.yml)

Use ~/.ralph/config.yml for defaults you want everywhere, such as shared backend settings, global lifecycle hooks, or organization-wide guardrails.

A common pattern is keeping notification hooks global while leaving project-specific automation in the repo-local ralph.yml:

# ~/.ralph/config.yml
hooks:
  enabled: true
  events:
    post.loop.complete:
      - name: notify-success
        command: ["./scripts/notify.sh", "complete"]
        on_error: warn
    post.loop.error:
      - name: notify-failure
        command: ["./scripts/notify.sh", "error"]
        on_error: warn

# ./ralph.yml
hooks:
  events:
    pre.loop.start:
      - name: env-guard
        command: ["./scripts/hooks/env-guard.sh"]
        on_error: block

With those two files, Ralph loads both and deep-merges them before validation and execution.

MCP Workspace Resolution

ralph mcp serve resolves its workspace root in this order:

1. --workspace-root <path>
2. RALPH_API_WORKSPACE_ROOT
3. current working directory

Use one MCP server instance per workspace/repo. Ralph's current control-plane APIs are workspace-scoped: config.*, task.*, loop.*, planning.*, and collection.* all read or persist state under a single root.

CLI Config Overrides

You can override specific core fields from the command line without creating a separate config file. This is useful for:

• Running parallel Ralph instances with isolated scratchpads
• Testing with different specs directories
• CI/CD pipelines with dynamic paths

Syntax: -c core.field=value

Supported fields:

Examples:

# Override scratchpad (loads ralph.yml + applies override)
ralph run -c core.scratchpad=.ralph/agent/feature-auth/scratchpad.md

# Explicit config + override
ralph run -c ralph.yml -c core.scratchpad=.ralph/agent/feature-auth/scratchpad.md

# Multiple overrides
ralph run -c core.scratchpad=.runs/task-1/scratchpad.md -c core.specs_dir=./custom-specs/

Overrides are applied after ralph.yml is loaded, so they take precedence. The scratchpad directory is auto-created if it doesn't exist.

Combined Config Compatibility (-c + -H)

Ralph supports both styles:

• Single-file combined config: -c ralph.yml with core + hats in one file
• Split config: -c <core> plus -H <hats source>

If both are used (-c contains hats and -H is provided), -H wins for workflow sections:

• hats and events from -H replace hats/events from -c
• event_loop values from -H override matching event_loop keys from -c
• -c core.*=... overrides still apply last

Full Configuration Reference

# Event loop settings
event_loop:
  completion_promise: "LOOP_COMPLETE"  # Output that signals completion
  max_iterations: 100                   # Maximum orchestration loops
  max_runtime_seconds: 14400            # 4 hours max runtime
  idle_timeout_secs: 1800               # 30 min idle timeout
  starting_event: "task.start"          # First event published (hat mode)
  checkpoint_interval: 5                # Git checkpoint frequency
  prompt_file: "PROMPT.md"              # Default prompt file

# CLI backend settings
cli:
  backend: "claude"                     # Backend name
  prompt_mode: "arg"                    # arg or stdin

# Core behaviors
core:
  scratchpad:                            # Scratchpad configuration
    enabled: true                        # Enable scratchpad (default: true)
    path: .ralph/agent/scratchpad.md     # Scratchpad file path
  specs_dir: "./specs/"                  # Specifications directory
  guardrails:                            # Rules injected into every prompt
    - "Fresh context each iteration"
    - "Never modify production database"

# Memories — persistent learning
memories:
  enabled: true                         # Enable memory system
  inject: auto                          # auto, manual, none
  budget: 2000                          # Max tokens to inject
  filter:
    types: []                           # Filter by memory type
    tags: []                            # Filter by memory tags
    recent: 0                           # Days limit (0 = no limit)

# Tasks — runtime work tracking
tasks:
  enabled: true                         # Enable task system

# Optional features
features:
  parallel: true                        # Allow worktree loops when primary lock is held
  auto_merge: false                     # Auto-merge worktree loops on completion
  preflight:
    enabled: false                      # Run preflight automatically on `ralph run`
    strict: false                       # Treat warnings as failures
    skip: []                            # Skip checks by name (for example: ["hooks"])

# Lifecycle hooks (v1)
hooks:
  enabled: false
  defaults:
    timeout_seconds: 30
    max_output_bytes: 8192
    suspend_mode: wait_for_resume
  events:
    pre.loop.start:
      - name: env-guard
        command: ["./scripts/hooks/env-guard.sh"]
        on_error: block
        mutate:
          enabled: false

# Hats — specialized personas
hats:
  my_hat:
    name: "My Hat"                      # Display name
    description: "Purpose"              # Optional description
    triggers: ["event.*"]               # Subscription patterns
    publishes: ["event.done"]           # Allowed event types
    default_publishes: "event.done"     # Default when no explicit
    max_activations: 10                 # Activation limit
    backend: "claude"                   # Backend override
    scratchpad:                         # Per-hat scratchpad override
      enabled: true                     #   Enable scratchpad (default: true)
      path: .ralph/agent/my-hat.md      #   Scratchpad file path. Inherits from core if omitted.
    instructions: |
      Hat-specific instructions...

Section Details

event_loop

Controls the orchestration loop behavior.

cli

Backend configuration.

Backend values:

• claude — Claude Code
• kiro — Kiro
• gemini — Gemini CLI
• codex — Codex
• amp — Amp
• copilot — Copilot CLI
• opencode — OpenCode
• pi — Pi
• custom — Custom adapter/backend

Prompt mode values:

• arg — Pass as CLI argument: cli -p "prompt"
• stdin — Pass via stdin: echo "prompt" | cli

core

Core behaviors, scratchpad, and guardrails.

The scratchpad field accepts a plain string (shorthand for setting path with enabled: true) or a structured object with enabled and path:

# String shorthand — sets path, enabled defaults to true
core:
  scratchpad: ".workspace/plan.md"

# Structured object — full control
core:
  scratchpad:
    enabled: true
    path: .ralph/agent/scratchpad.md

Solo mode safety: If scratchpad is disabled (enabled: false) but no hats are defined, Ralph force-enables it with a warning. Scratchpad is the only continuity mechanism in solo mode.

memories

Persistent learning across sessions.

Injection modes:

• auto — Automatically inject at iteration start
• manual — Agent must call ralph tools memory prime
• none — No injection

tasks

Runtime work tracking.

features

Optional runtime capabilities.

When features.preflight.enabled: true, ralph run uses the default preflight suite: config, hooks, backend, telegram, git, paths, tools, and specs.

hooks

Lifecycle hooks for orchestrator phase-events (v1).

Hooks can be defined in either the user-level ~/.ralph/config.yml or the workspace ralph.yml. Ralph loads the user config first, then overlays the project config on top. That means hooks in the user config apply globally unless the project config replaces the same event mapping.

Supported v1 lifecycle phase-event keys under hooks.events:

• pre.loop.start, post.loop.start
• pre.iteration.start, post.iteration.start
• pre.plan.created, post.plan.created
• pre.human.interact, post.human.interact
• pre.loop.complete, post.loop.complete
• pre.loop.error, post.loop.error

Hook spec (HookSpec) fields:

Mutation scope in v1 is intentionally narrow:

• Mutation parsing only happens when mutate.enabled: true.
• Hook stdout must be JSON using the v1 contract: {"metadata": { ... }}.
• Only metadata namespace updates are allowed (metadata.accumulated.hook_metadata.<hook_name>).
• Prompt/event/config mutation is out of scope for v1.

Minimal runnable example:

• Config: examples/hooks/minimal/ralph.hooks.yml
• Scripts: examples/hooks/scripts/env-guard.sh, examples/hooks/scripts/notify.sh
• Validate: ralph hooks validate -c examples/hooks/minimal/ralph.hooks.yml

hats

Specialized personas for hat-based mode.

Each hat can override the global scratchpad with its own scratchpad field. Like the core-level setting, it accepts a plain string or a structured object:

hats:
  planner:
    scratchpad: .ralph/agent/planner.md       # String shorthand
    # ...
  builder:
    scratchpad:
      path: .ralph/agent/builder.md           # Structured with custom path
    # ...
  validator:
    scratchpad:
      enabled: false                          # Disable scratchpad entirely
    # ...
  reviewer:                                   # No scratchpad key = inherits global
    # ...