Options Reference | Ralph TUI

Configuration Options Reference

This page documents every configuration option available in Ralph TUI. Options can be set in config files (TOML) or via CLI flags.

INFO

Most options have sensible defaults. You typically only need to configure the agent and tracker for your project.

Core Settings

These control basic execution behavior.

Option	Type	Default	Description
`agent`	string	-	Agent plugin to use (e.g., "claude", "opencode")
`command`	string	-	Custom command/executable for the agent (e.g., "ccr code")
`tracker`	string	-	Tracker plugin to use (e.g., "beads-bv", "json")
`maxIterations`	number	`10`	Maximum iterations per session (0 = unlimited, max 1000)
`iterationDelay`	number	`1000`	Delay between iterations in milliseconds (max 300000)
`outputDir`	string	`.ralph-tui/iterations`	Directory for iteration log files
`progressFile`	string	`.ralph-tui/progress.md`	Progress file for cross-iteration context
`autoCommit`	boolean	`false`	Auto-commit after each completed task
`prompt_template`	string	-	Custom Handlebars template path
`subagentTracingDetail`	string	`"off"`	Subagent visibility level
`skills_dir`	string	-	Directory containing custom PRD skills

subagentTracingDetail Values

Controls how much information about subagent activity is displayed:

Value	Description
`"off"`	No tracing, show raw agent output only
`"minimal"`	Show start/complete events
`"moderate"`	Show events with description and duration
`"full"`	Show events with nested output and hierarchy

Agent Options

Shorthand Configuration

The simplest way to configure an agent:

TOML

agent = "claude"
 
[agentOptions]
model = "claude-sonnet-4-20250514"

Option	Type	Default	Description
`agent`	string	-	Agent plugin name
`command`	string	-	Custom command/executable path (see below)
`agentOptions`	object	`{}`	Plugin-specific options

Custom Command

The command option lets you specify a custom binary or wrapper for your agent. This is useful for:

AI routing tools like Claude Code Router (CCR) that proxy to different providers
Custom wrappers that add logging, authentication, or other behavior
Alternative binary locations when the default isn't in PATH

TOML

agent = "claude"
command = "ccr code"

This uses the Claude agent plugin but routes requests through CCR, which can proxy to OpenRouter, DeepSeek, Ollama, Gemini, or other providers.

Precedence

The command follows this precedence (highest to lowest):

Agent-specific: command field in [[agents]] array
Top-level: command field (this option)
Plugin default: e.g., "claude" for the Claude plugin

INFO

For security, the command field cannot contain shell metacharacters (;, &, |, `, $, (, )). If you need complex command logic, create a wrapper script.

Full Agent Configuration

For advanced setups with multiple agents:

TOML

[[agents]]
name = "my-agent"
plugin = "claude"
default = true
command = "claude"
defaultFlags = ["--no-confirm"]
timeout = 300000
 
  [agents.options]
  model = "claude-sonnet-4-20250514"
 
  [agents.rateLimitHandling]
  enabled = true
  maxRetries = 3

Option	Type	Default	Description
`name`	string	required	Unique identifier for this agent config
`plugin`	string	required	Plugin type ("claude", "opencode")
`default`	boolean	`false`	Use as default agent
`command`	string	(from plugin)	Override executable command
`defaultFlags`	string[]	`[]`	Additional CLI flags
`timeout`	number	`0`	Execution timeout (ms, 0 = no timeout)
`options`	object	`{}`	Plugin-specific options
`fallbackAgents`	string[]	`[]`	Agents to try on rate limit
`rateLimitHandling`	object	-	Rate limit configuration

Tracker Options

Shorthand Configuration

TOML

tracker = "beads-bv"
 
[trackerOptions]
epicId = "beads-001"

Option	Type	Default	Description
`tracker`	string	-	Tracker plugin name
`trackerOptions`	object	`{}`	Plugin-specific options

Full Tracker Configuration

TOML

[[trackers]]
name = "my-tracker"
plugin = "beads-bv"
default = true
 
  [trackers.options]
  epicId = "beads-001"

Option	Type	Default	Description
`name`	string	required	Unique identifier
`plugin`	string	required	Plugin type ("json", "beads-bv", "beads")
`default`	boolean	`false`	Use as default tracker
`options`	object	`{}`	Plugin-specific options

Tracker Plugin Options

Each tracker plugin accepts specific options:

JSON Tracker

For prd.json task files:

Option	Type	Description
`path`	string	Path to prd.json file

Beads-BV Tracker

For Beads issues with BV triage:

Option	Type	Description
`epicId`	string	Epic ID to filter tasks

Beads Tracker

For basic Beads integration:

Option	Type	Description
`epicId`	string	Epic ID to filter tasks

Error Handling

Controls how Ralph responds to task failures.

TOML

[errorHandling]
strategy = "skip"
maxRetries = 3
retryDelayMs = 5000
continueOnNonZeroExit = false

Option	Type	Default	Description
`strategy`	string	`"skip"`	Error handling strategy
`maxRetries`	number	`3`	Max retry attempts (0-10)
`retryDelayMs`	number	`5000`	Delay between retries (0-300000 ms)
`continueOnNonZeroExit`	boolean	`false`	Continue if agent exits non-zero

Strategy Values

Value	Description
`"retry"`	Retry the task up to `maxRetries` times
`"skip"`	Skip the failed task and continue to next
`"abort"`	Stop execution immediately on failure

INFO

Use "abort" for CI pipelines where any failure should stop the build. Use "skip" for development where you want to see all issues.

Rate Limit Handling

Controls fallback behavior when the primary agent hits API rate limits.

TOML

fallbackAgents = ["opencode"]
 
[rateLimitHandling]
enabled = true
maxRetries = 3
baseBackoffMs = 5000
recoverPrimaryBetweenIterations = true

Option	Type	Default	Description
`fallbackAgents`	string[]	`[]`	Ordered list of fallback agents
`rateLimitHandling.enabled`	boolean	`true`	Enable rate limit handling
`rateLimitHandling.maxRetries`	number	`3`	Retries before fallback (0-10)
`rateLimitHandling.baseBackoffMs`	number	`5000`	Base backoff time (0-300000 ms)
`rateLimitHandling.recoverPrimaryBetweenIterations`	boolean	`true`	Try primary between iterations

Notifications

Configure desktop notifications for iteration events.

TOML

[notifications]
enabled = true
sound = "off"

Option	Type	Default	Description
`enabled`	boolean	`true`	Enable desktop notifications
`sound`	string	`"off"`	Notification sound mode

Sound Mode Values

Value	Description
`"off"`	No sound
`"system"`	Use OS default notification sound
`"ralph"`	Play random Ralph Wiggum sound clips

Custom Skills Directory

Configure a skills_dir to use custom PRD skills with the --prd-skill flag:

TOML

skills_dir = "/path/to/my-skills"

Skills Directory Structure

Skills must be folders inside skills_dir containing a SKILL.md file:

my-skills/
├── custom-prd-skill/
│   └── SKILL.md
├── another-skill/
│   └── SKILL.md

Using Custom Skills

Bash

# Use a custom skill with create-prd
ralph-tui create-prd --chat --prd-skill custom-prd-skill

INFO

Using --prd-skill requires skills_dir to be set in your config file. The command will fail with a clear error if skills_dir is not configured.

PRD Format Requirements for Custom Skills

Custom skills must generate PRDs compatible with task creation. Required format:

Markdown

# Feature Name
 
## Quality Gates (optional but recommended)
 
These commands must pass for every user story:
- `bun run typecheck`
- `bun run lint`
 
## User Stories
 
### US-001: Story Title
 
**As a** [user type]
**I want** [capability]
**So that** [benefit]
 
#### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
 
### US-002: Another Story
...

INFO

If a custom skill generates a PRD without user stories matching ### US-XXX: pattern, task creation will fail with a clear error message.

CLI Flag Reference

These flags override config file settings. Use with any execution command.

Execution Options

Flag	Short	Type	Description
`--iterations <n>`	`-n`	number	Max iterations
`--delay <ms>`		number	Iteration delay
`--output-dir <path>`		string	Output directory
`--progress-file <path>`		string	Progress file path
`--headless`		boolean	Run without TUI
`--no-setup`		boolean	Skip setup check

Agent Options

Flag	Short	Type	Description
`--agent <name>`	`-a`	string	Agent to use
`--model <model>`	`-m`	string	Model override

Tracker Options

Flag	Short	Type	Description
`--tracker <name>`	`-t`	string	Tracker to use
`--epic <id>`	`-e`	string	Epic ID (beads trackers)
`--prd <path>`	`-p`	string	PRD file path (json tracker)

Error Handling Options

Flag	Type	Description
`--on-error <strategy>`	string	Error strategy (retry/skip/abort)
`--max-retries <n>`	number	Max retry attempts

Prompt Options

Flag	Type	Description
`--prompt <path>`	string	Custom prompt template

Notification Options

Flag	Type	Description
`--notify`	boolean	Enable notifications
`--no-notify`	boolean	Disable notifications

Validation Constraints

All numeric options have validation constraints:

Option	Min	Max
`maxIterations`	0	1000
`iterationDelay`	0	300000
`errorHandling.maxRetries`	0	10
`errorHandling.retryDelayMs`	0	300000
`rateLimitHandling.maxRetries`	0	10
`rateLimitHandling.baseBackoffMs`	0	300000

Environment Variables

Ralph TUI respects these environment variables:

Variable	Description
`XDG_CONFIG_HOME`	Override global config location (default: `~/.config`)

Next Steps

Config File - Full config file examples
CLI Commands - Command documentation
Plugins - Agent and tracker plugin details