Options Reference

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.

Core Settings

These control basic execution behavior.

subagentTracingDetail Values

Controls how much information about subagent activity is displayed:

Agent Options

Shorthand Configuration

The simplest way to configure an agent:

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

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

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):

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

Full Agent Configuration

For advanced setups with multiple agents:

[[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

Tracker Options

Shorthand Configuration

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

Full Tracker Configuration

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

Tracker Plugin Options

Each tracker plugin accepts specific options:

JSON Tracker

For prd.json task files:

Beads-BV Tracker

For Beads issues with BV triage:

Beads Tracker

For basic Beads integration:

Error Handling

Controls how Ralph responds to task failures.

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

Strategy Values

Rate Limit Handling

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

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

Environment Variable Exclusion

Controls which environment variables are passed to agent subprocesses. This is essential when your shell environment contains API keys that conflict with the agent's authentication method.

The Problem

When you run ralph-tui from a directory containing a .env or .env.local file, runtimes like Bun or tools like direnv and dotenv-cli may automatically load these variables into your shell environment. If one of these variables is an API key (e.g., ANTHROPIC_API_KEY), the agent CLI will use it instead of your intended authentication method (like a Max subscription), causing unexpected billing.

Default Exclusion Patterns

Ralph TUI automatically excludes environment variables matching these patterns from agent subprocesses:

• *_API_KEY — blocks ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.
• *_SECRET_KEY — blocks AWS_SECRET_KEY, etc.
• *_SECRET — blocks DB_SECRET, JWT_SECRET, etc.

These defaults are always active, even without any configuration. You'll see which variables are blocked (and which are allowed through) in the startup output of ralph-tui run, ralph-tui prime, ralph-tui doctor, and ralph-tui info.

envPassthrough: Allowing Specific Variables

If you need a blocked variable to reach the agent (e.g., when the agent genuinely needs the API key), use envPassthrough to override the exclusion:

# Allow ANTHROPIC_API_KEY through despite matching *_API_KEY
envPassthrough = ["ANTHROPIC_API_KEY"]

Passthrough supports glob patterns:

# Allow all *_API_KEY variables through
envPassthrough = ["*_API_KEY"]

envExclude: Additional Exclusions

The envExclude option adds patterns on top of the defaults. Use it to block variables not covered by the default patterns:

# Block tokens and passwords in addition to defaults
envExclude = ["*_TOKEN", "*_PASSWORD"]

Three-Layer Filtering

Environment variables are filtered through three layers (in order):

1. Default patterns — *_API_KEY, *_SECRET_KEY, *_SECRET (always applied)
2. User envExclude — additional patterns you configure (stacked on defaults)
3. envPassthrough — overrides both defaults and user excludes

process.env variables
  │
  ├─ Matches default pattern? ──── BLOCKED (unless in passthrough)
  ├─ Matches envExclude?      ──── BLOCKED (unless in passthrough)
  ├─ Matches envPassthrough?  ──── ALLOWED (overrides exclusion)
  └─ No pattern match         ──── ALLOWED (passed through)

Shorthand Configuration

Apply to the default agent with top-level settings:

agent = "claude"
envExclude = ["*_TOKEN"]
envPassthrough = ["ANTHROPIC_API_KEY"]

Per-Agent Configuration

Apply to specific agents in the [[agents]] array:

[[agents]]
name = "claude-max"
plugin = "claude"
# Uses defaults - ANTHROPIC_API_KEY is blocked
 
[[agents]]
name = "claude-api"
plugin = "claude"
envPassthrough = ["ANTHROPIC_API_KEY"]
# Explicitly allows the API key through for API-based auth

Glob Pattern Syntax

Both envExclude and envPassthrough patterns support glob-style wildcards:

Common Use Cases

Use Max subscription (default behavior, no config needed):

# ANTHROPIC_API_KEY is blocked by default
agent = "claude"

Explicitly use API key authentication:

agent = "claude"
envPassthrough = ["ANTHROPIC_API_KEY"]

Block additional sensitive variables:

envExclude = ["*_TOKEN", "*_PASSWORD", "DATABASE_URL"]

Multiple agents with different auth methods:

[[agents]]
name = "claude-max"
plugin = "claude"
# Default: ANTHROPIC_API_KEY blocked, uses Max subscription
 
[[agents]]
name = "claude-api"
plugin = "claude"
envPassthrough = ["ANTHROPIC_API_KEY"]
# Uses API key from environment

Diagnostics

Run ralph-tui doctor to see which variables are blocked vs. allowed:

Env filter:
  Blocked:     ANTHROPIC_API_KEY, OPENAI_API_KEY
  Passthrough: (none)

Or if nothing matches:

Env filter: no vars matched exclusion patterns (*_API_KEY, *_SECRET_KEY, *_SECRET)

Notifications

Configure desktop notifications for iteration events.

[notifications]
enabled = true
sound = "off"

Sound Mode Values

Parallel Execution

Configure parallel execution behavior.

[parallel]
mode = "never"
maxWorkers = 3
directMerge = false

Mode Values

CLI Flags

See the Parallel Execution guide for detailed documentation.

Custom Skills Directory

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

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

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

PRD Format Requirements for Custom Skills

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

# 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
...

CLI Flag Reference

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

Execution Options

Agent Options

Tracker Options

Error Handling Options

Prompt Options

Prompt Template Precedence

Ralph TUI resolves prompt templates in this order (first match wins):

Notification Options

Validation Constraints

All numeric options have validation constraints:

Environment Variables

Ralph TUI respects these environment variables:

Environment Variable Filtering

Ralph TUI automatically excludes variables matching *_API_KEY, *_SECRET_KEY, and *_SECRET from agent subprocesses. Use envPassthrough to allow specific variables through, or envExclude to block additional patterns:

# Allow a specific key through (overrides default block)
envPassthrough = ["ANTHROPIC_API_KEY"]
 
# Block additional patterns beyond defaults
envExclude = ["*_TOKEN", "DATABASE_URL"]

See Environment Variable Exclusion for the full three-layer filtering details.

Next Steps

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