Configuration Reference¶

New to Ralph Workflow? Start with Getting Started before diving into config details.

Ralph Workflow is a free and open-source AI agent orchestration system built around a simple Ralph-loop core. That simple core composes into a stronger composable workflow system for substantial, well-specified repo work, and the default workflow is already strong enough to start with before you customize anything.

Ralph Workflow keeps the core loop simple, but operators still need direct answers about which TOML file to edit, which scope wins, and how to validate changes safely. Start with the default workflow before you customize anything, then use this page when you need exact file and precedence guidance.

Use this page when your question is about files, precedence, validation commands, or configuration edits. If you want docs routed by use case instead of page type, open End-User Stories.

This page answers the operator question quickly: which file do I edit, at which scope, and how do I validate the change safely? Ralph Workflow keeps the core simple, but the docs should still point you straight to the right TOML file instead of making you reverse-engineer the policy layout.

Bring your existing coding agents and keep your keys to yourself. Most operators mainly need to wire Ralph Workflow into agent CLIs they already trust, not re-home their model secrets.

If your immediate question is “Where do I edit ralph-workflow.toml?”, the short answer is:

Global defaults for all projects → ~/.config/ralph-workflow.toml
Project-specific override for just this repo → .agent/ralph-workflow.toml

If .agent/ralph-workflow.toml does not exist yet, create it with:

ralph --init-local-config

After editing config, validate it with:

ralph --check-config
ralph --check-policy

Ralph Workflow uses layered configuration. Settings are resolved in this order, highest priority first:

CLI flags
Project-local config — .agent/ralph-workflow.toml
User-global config — ~/.config/ralph-workflow.toml
Bundled defaults — shipped in ralph/policy/defaults/

The files most operators care about¶

Ralph Workflow manages a standard config set across two scopes.

User-global files¶

File	Purpose
`~/.config/ralph-workflow.toml`	Global defaults: agent selection, iteration counts, verbosity
`~/.config/ralph-workflow-mcp.toml`	MCP server definitions shared across projects
`~/.config/ralph-workflow-pipeline.toml`	Global pipeline defaults when a workspace has no local pipeline override
`~/.config/ralph-workflow-artifacts.toml`	Global artifact defaults when a workspace has no local artifact override

Project-local files¶

File	Purpose
`.agent/mcp.toml`	Project-specific MCP server definitions
`.agent/pipeline.toml`	Workflow phases, routing, and parallel settings
`.agent/artifacts.toml`	Artifact type schemas and contracts
`.agent/ralph-workflow.toml`	Optional project-specific overrides for agents, chains, drains, and main settings

Run ralph --init to create the standard project-local support files. Use ralph --init-local-config when you explicitly want a project-local copy of the main config.

Advanced config map¶

If you already know you want the deeper docs, use this map instead of scanning the whole manual:

I want to change…	Open this page
agent selection, retry behavior, verbosity, or drain bindings	this page: Configuration Reference
workflow phases, loopbacks, commit routes, fan-out, counters, or recovery	Advanced Pipeline Configuration
artifact contracts, decision vocabularies, summary files, or commit-message artifacts	Advanced Artifact Configuration
MCP servers, web search, crawl, or media/web-visit integrations	Advanced MCP Configuration
what the active policy means after all config layers resolve	Policy Explanation

Which file should I edit?¶

Use this rule of thumb:

I want this behavior in every repo I run → edit ~/.config/ralph-workflow.toml
I only want this behavior in one repo → edit .agent/ralph-workflow.toml
I want to change workflow phases, loopbacks, or phase-owned policy → edit .agent/pipeline.toml
I want to change MCP servers or web/search access → edit ~/.config/ralph-workflow-mcp.toml or .agent/mcp.toml
I want to change artifact contracts/history → edit .agent/artifacts.toml

The common mistake is editing ralph-workflow.toml when the real change belongs in pipeline.toml. The main ralph-workflow.toml file is mostly for:

agent selection and fallback chains
drain-to-chain bindings
retry / timeout / verbosity settings
Claude Code Switch / agent definitions

The workflow structure itself lives in pipeline.toml.

The fastest safe workflow for editing config¶

Decide whether the change is global or repo-local.
Edit the right TOML file.
Run ralph --check-config.
If you changed workflow behavior, also run ralph --check-policy.
Run ralph --diagnose before the next real unattended run.

If you want the active workflow explained in plain English after the config change, run:

ralph --explain-policy

Most common user edits in `ralph-workflow.toml`¶

Most end users do not need to invent a policy from scratch. They usually want one of these changes:

change which agents are used for planning / development / analysis / commit
increase or decrease retry / cycle behavior
raise or lower verbosity
set git author info for automated commits
create a project-local override without affecting every repo

Bundled defaults¶

The bundled defaults live in ralph/policy/defaults/. When in doubt, the files themselves are the most exact reference:

ralph-workflow.toml — main config
mcp.toml — MCP server config
pipeline.toml — workflow phases and routing
artifacts.toml — artifact contracts

Common settings in `ralph-workflow.toml`¶

The main config file is ~/.config/ralph-workflow.toml, with optional project-level overrides in .agent/ralph-workflow.toml.

`[general]`¶

Core workflow settings: verbosity, git identity, retry behavior, and liveness limits.

Key	Default	Description
`verbosity`	`2`	Output verbosity: 0=quiet, 1=normal, 2=verbose, 3=full, 4=debug
`git_user_name`	(from git config)	Git author name for commits
`git_user_email`	(from git config)	Git author email for commits
`max_retries`	`3`	Max retries per agent attempt when synthesized from the main config
`retry_delay_ms`	`1000`	Base delay between retries
`backoff_multiplier`	`2.0`	Exponential backoff multiplier
`max_backoff_ms`	`60000`	Maximum retry backoff delay
`max_cycles`	`3`	Maximum full fallback cycles through a drain
`agent_idle_timeout_seconds`	`300.0`	Max idle seconds before a stalled agent is terminated

Example: change verbosity globally¶

[general]
verbosity = 3

Use this when you want richer logs in every project.

Example: set git author info globally¶

[general]
git_user_name = "Your Name"
git_user_email = "you@example.com"

Example: make one repo quieter without changing everything else¶

Create .agent/ralph-workflow.toml:

[general]
verbosity = 1

`[general.workflow]`¶

Key	Default	Description
`checkpoint_enabled`	`true`	Enable checkpoint/resume support

`[prompt_helper]`¶

Configuration for the interactive prompt-refinement helper launched by ralph --prompt-helper or ralph-prompt.

Key	Default	Description
`agent`	(none)	Agent name to use for the prompt-helper session. Omitting this setting causes Ralph Workflow to use the first configured agent in `[agents.*]`. If no agents are configured at all, Ralph Workflow falls back to the built-in `opencode` agent. An explicitly named but unavailable agent raises an error instead of silently falling back.

Example:

[prompt_helper]
agent = "claude"

The helper does not expose drain configuration, fallback chains, or agent chains — it uses a single interactive agent with an internal standalone session only. See the CLI Reference for usage.

Agent chains and drains¶

Most operator customization happens in [agent_chains] and [agent_drains] inside ralph-workflow.toml.

[general]
max_retries = 3
retry_delay_ms = 1000

[agent_chains]
planning = ["claude/opus"]
development = ["agy", "opencode/minimax/MiniMax-M2.7-highspeed", "codex", "claude/sonnet"]
analysis = ["opencode/openai/gpt-5.4"]
commit = ["claude/haiku"]

[agent_drains]
planning = "planning"
planning_analysis = "analysis"
development = "development"
development_analysis = "analysis"
development_commit = "commit"

agy (Google Anti Gravity) is also a valid agent name in any chain alongside claude, codex, and opencode.

In practice:

chains define fallback order for one kind of work
drains map workflow steps to those chains

Multiple drains can point at the same chain. That lets you change agent policy without rewriting the workflow itself.

Example: switch development to a different fallback order¶

[agent_chains]
development = ["agy", "codex", "claude/sonnet"]

Use this when your main question is “which coding agent should Ralph Workflow try first during implementation?” — valid agent names include claude, codex, opencode, and agy.

Example: use a repo-local override for one project only¶

If one repo needs a stricter or more expensive development chain than your default setup, put only the override in .agent/ralph-workflow.toml:

[agent_chains]
development = ["claude/opus", "codex"]

That repo-local file overrides the global chain just for that repo.

User stories: what to edit for common goals¶

I want Ralph Workflow to use different coding agents¶

Edit ralph-workflow.toml → [agent_chains].

I want one repo to behave differently from my defaults¶

Create or edit .agent/ralph-workflow.toml.

I want to change the workflow shape itself¶

Edit .agent/pipeline.toml, not ralph-workflow.toml.

Then read Advanced Pipeline Configuration.

I want to enable or customize MCP / web tools¶

Edit ralph-workflow-mcp.toml or .agent/mcp.toml.

Then read Advanced MCP Configuration.

I want to change artifact contracts, decision vocabularies, or summary file outputs¶

Edit .agent/artifacts.toml.

Then read Advanced Artifact Configuration.

I want to understand what my policy now does after editing it¶

Run:

ralph --check-policy
ralph --explain-policy

I broke my config and want to get back to a known-good baseline¶

Run:

ralph --regenerate-config

Ralph Workflow backs up overwritten files with a .bak suffix.

`pipeline.toml` in plain language¶

pipeline.toml defines the workflow shape Ralph Workflow uses for a run.

The top-level ideas are:

entry_phase — where the run starts
terminal_phase — what counts as successful completion
[phases.<name>] — the individual steps in the workflow
transitions — where Ralph Workflow goes next on success, failure, or loopback
counters and budgets — how Ralph Workflow limits iteration and retry behavior
post-commit routes — what happens after a commit-producing step
parallel execution — whether independent work units can fan out concurrently

Development proof policy¶

The development phase now supports a proof policy block in pipeline.toml:

[phases.development.artifact_proof_policy]
require_plan_proof = true
require_analysis_proof = true

Omitting this block inherits the bundled defaults. To disable proof enforcement in a project-local .agent/pipeline.toml, set both fields to false explicitly. The proof policy is phase-owned, so it lives under [phases.development] alongside the other phase settings.

Per-phase display style (`display_style`)¶

Each phase can declare a display_style override in pipeline.toml to control the color of its phase banner:

[phases.planning]
display_style = "theme.phase.planning"

When set, this style string is used instead of the role-based default. Without display_style, phases inherit a color from their role — for example both planning and development share role='execution' and would otherwise render identically. Set display_style to give each phase a visually distinct banner. Available theme keys include theme.phase.planning, theme.phase.development, theme.phase.development_analysis, theme.phase.commit, and others defined in ralph.display.theme.

Advanced sections you may not need right away¶

The main config also supports deeper transport-specific and workflow-authoring sections such as:

[ccs] / [ccs_aliases] for explicitly-headless Claude Code Switch defaults
[agents.*] for agent defaults, including transport = 'claude_interactive' on the built-in claude path
loop counters and budget counters
review-role bypass routes
recovery policy tuning
parallel fan-out controls

Those sections are useful when you are customizing Ralph Workflow deeply, but many operators never need to touch them. Use claude-headless or CCS when you explicitly want the documented non-interactive Claude path.

When to read further¶

Use the more detailed docs when you need them:

Concepts — terms like phase, drain, and artifact
CLI Reference — runtime flags and shortcuts
Policy Explanation — inspect the active workflow in plain English
Advanced Pipeline Configuration — phases, routing, counters, recovery, and fan-out
Advanced Artifact Configuration — artifact contracts, decision vocabularies, and summaries
Advanced MCP Configuration — MCP servers, search, crawl, and web tooling
Developer Reference — implementation-oriented detail
End-User Stories — common user goals and the shortest docs path for each one If you want the advanced/operator version of this topic — phases, counters, commit policy, recovery, and parallel fan-out — use Advanced Pipeline Configuration.

`artifacts.toml` in plain language¶

artifacts.toml defines the typed outputs Ralph Workflow expects from each drain.