Configuration

Ralph uses a layered configuration system that allows you to set global defaults and override them per-project. This flexibility lets you customize timeouts, retries, notifications, and more to match your workflow.

Configuration Hierarchy

Ralph merges configuration from two levels:

Global Config (~/.ralph/config.json)
    ↓
Project Config (~/.ralph/projects/<project>/config.json)
    ↓
Effective Configuration (merged, project overrides global)

Configuration Files

Viewing Configuration

See your current effective configuration:

ralph config

Output shows merged settings:

{
  "agent": "cursor",
  "maxRetries": 3,
  "retryDelayMs": 5000,
  "agentTimeoutMs": 1800000,
  "stuckThresholdMs": 300000,
  "maxRuntimeMs": 0,
  "notifications": {
    "systemNotification": true
  }
}

With source information:

ralph config --verbose

Shows which settings come from global vs project config.

Initial Setup

Configure global preferences interactively:

ralph setup

This wizard walks you through:

1. Agent Selection — Choose Cursor CLI, Claude Code, or Codex
2. Timeout Settings — Configure iteration and stuck thresholds
3. Retry Behavior — Set max retries and delays
4. Notifications — Enable system notifications or webhooks

Configuration Options

Agent Selection

Choose which AI agent Ralph uses:

{
  "agent": "cursor"
}

When to change:

• Switching between different AI agents
• Testing which agent works best for your project
• Using different agents for different projects

Example:

# Global: Use Cursor by default
echo '{"agent": "cursor"}' > ~/.ralph/config.json

# Project: Use Claude for this specific project
echo '{"agent": "claude"}' > ~/.ralph/projects/my-project/config.json

Retry Settings

Control how Ralph handles failed iterations:

{
  "maxRetries": 3,
  "retryDelayMs": 5000
}

When to adjust:

• Increase retries for complex tasks that often need multiple attempts
• Decrease retries to fail fast and move on
• Increase delay if agent needs time to recover between attempts
• Decrease delay for faster iteration cycles

Examples:

// Patient: More retries for complex projects
{
  "maxRetries": 5,
  "retryDelayMs": 10000
}

// Fast-fail: Fewer retries for simple tasks
{
  "maxRetries": 1,
  "retryDelayMs": 1000
}

Timeout Settings

Control iteration and session time limits:

{
  "agentTimeoutMs": 1800000,
  "stuckThresholdMs": 300000,
  "maxRuntimeMs": 0
}

When to adjust:

agentTimeoutMs:

• Increase for complex tasks (large refactors, migrations)
• Decrease for simple tasks to fail faster

stuckThresholdMs:

• Increase if agent legitimately needs long pauses
• Decrease to detect stuck states faster

maxRuntimeMs:

• Set for overnight runs to prevent infinite sessions
• Leave at 0 for unlimited development time

Examples:

// Long-running complex tasks
{
  "agentTimeoutMs": 3600000,    // 1 hour per iteration
  "stuckThresholdMs": 600000,   // 10 min stuck threshold
  "maxRuntimeMs": 28800000      // 8 hour max session
}

// Quick iterations
{
  "agentTimeoutMs": 600000,     // 10 min per iteration
  "stuckThresholdMs": 120000,   // 2 min stuck threshold
  "maxRuntimeMs": 0             // No session limit
}

Notification Settings

Get notified when sessions complete:

{
  "notifications": {
    "systemNotification": true,
    "webhookUrl": "https://hooks.slack.com/services/...",
    "markerFilePath": ".ralph/complete.marker"
  }
}

Use cases:

System Notifications:

{
  "notifications": {
    "systemNotification": true
  }
}

Get a desktop notification when Ralph finishes.

Slack Webhook:

{
  "notifications": {
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX"
  }
}

Post to Slack channel when session completes.

Marker File:

{
  "notifications": {
    "markerFilePath": ".ralph/complete.marker"
  }
}

Create a file that other scripts can watch for.

All Together:

{
  "notifications": {
    "systemNotification": true,
    "webhookUrl": "https://hooks.slack.com/services/...",
    "markerFilePath": ".ralph/complete.marker"
  }
}

Memory Settings

Control memory usage and garbage collection:

{
  "memory": {
    "maxOutputBufferBytes": 5242880,
    "memoryWarningThresholdMb": 500,
    "memoryThresholdMb": 1024,
    "enableGarbageCollectionHints": true
  }
}

When to adjust:

• Decrease buffer if running on low-memory systems
• Increase thresholds for long-running sessions
• Disable GC hints if experiencing performance issues

Examples:

// Low-memory system
{
  "memory": {
    "maxOutputBufferBytes": 2621440,      // 2.5 MB
    "memoryWarningThresholdMb": 250,
    "memoryThresholdMb": 512
  }
}

// High-memory system with long sessions
{
  "memory": {
    "maxOutputBufferBytes": 10485760,     // 10 MB
    "memoryWarningThresholdMb": 1000,
    "memoryThresholdMb": 2048
  }
}

Configuration Examples

Development Laptop

Fast iterations, desktop notifications:

{
  "agent": "cursor",
  "maxRetries": 3,
  "retryDelayMs": 5000,
  "agentTimeoutMs": 1800000,
  "stuckThresholdMs": 300000,
  "notifications": {
    "systemNotification": true
  }
}

CI/CD Server

No notifications, strict timeouts:

{
  "agent": "cursor",
  "maxRetries": 2,
  "retryDelayMs": 2000,
  "agentTimeoutMs": 600000,
  "stuckThresholdMs": 120000,
  "maxRuntimeMs": 3600000,
  "notifications": {
    "systemNotification": false,
    "markerFilePath": "/tmp/ralph-complete"
  }
}

Overnight Long-Running Session

Extended timeouts, Slack notifications:

{
  "agent": "cursor",
  "maxRetries": 5,
  "retryDelayMs": 10000,
  "agentTimeoutMs": 3600000,
  "stuckThresholdMs": 600000,
  "maxRuntimeMs": 28800000,
  "notifications": {
    "systemNotification": true,
    "webhookUrl": "https://hooks.slack.com/services/..."
  },
  "memory": {
    "maxOutputBufferBytes": 10485760,
    "memoryWarningThresholdMb": 1000
  }
}

Complex Refactoring Project

Patient retries, long timeouts:

{
  "agent": "claude",
  "maxRetries": 5,
  "retryDelayMs": 15000,
  "agentTimeoutMs": 5400000,
  "stuckThresholdMs": 900000,
  "notifications": {
    "systemNotification": true
  }
}

Custom Instructions

Add project-specific instructions that are included in every agent prompt.

Create ~/.ralph/projects/<project>/instructions.md:

# Project Instructions

## Technology Stack
- TypeScript with strict mode
- Bun as runtime and package manager
- Prisma for database operations
- Express for API server

## Code Standards
- Use functional programming patterns
- Prefer immutability
- Write descriptive variable names
- Add JSDoc comments for public APIs

## Project Structure
- API routes in src/routes/
- Business logic in src/services/
- Database models in src/models/
- Utilities in src/lib/

## Testing
- Write tests in __tests__/ directories
- Use Bun's test runner
- Aim for 80%+ coverage

Ralph includes these instructions in every iteration, ensuring the agent follows your project’s conventions.

Per-Project Configuration

Override global settings for specific projects:

cd my-project

# Create project config
cat > ~/.ralph/projects/my-project/config.json << EOF
{
  "agent": "claude",
  "agentTimeoutMs": 3600000,
  "maxRetries": 5
}
EOF

Now this project uses Claude with longer timeouts, while other projects use global settings.

Environment Variables

Some settings can be overridden with environment variables:

# Override agent for one session
RALPH_AGENT=claude ralph run

# Override timeout
RALPH_TIMEOUT=3600000 ralph run

# Run with debug logging
RALPH_DEBUG=true ralph run

Configuration Best Practices

Start with Defaults

Don’t over-configure initially. Use defaults and adjust based on experience:

{
  "agent": "cursor"
}

Tune Per Project

Different projects have different needs:

• Simple CRUD apps: Default timeouts work fine
• Complex refactors: Increase timeouts and retries
• Large migrations: Increase all limits

Monitor and Adjust

Watch for patterns:

• Frequent timeouts: Increase agentTimeoutMs
• Agent getting stuck: Decrease stuckThresholdMs
• Tasks failing repeatedly: Increase maxRetries

Use Project Config for Exceptions

Keep global config simple, use project config for special cases:

# Global: Sensible defaults
~/.ralph/config.json

# Project: Special requirements
~/.ralph/projects/legacy-refactor/config.json

Troubleshooting Configuration

Configuration Not Taking Effect

Problem: Changed config but behavior unchanged

Solutions:

1. Verify config file syntax (must be valid JSON)
2. Check you’re editing the right file (global vs project)
3. Restart session after config changes
4. Verify with ralph config

Invalid Configuration

Problem: Ralph reports invalid config

Solution: Validate JSON syntax:

# Check global config
cat ~/.ralph/config.json | jq .

# Check project config
cat ~/.ralph/projects/my-project/config.json | jq .

Settings Conflict

Problem: Unsure which settings are active

Solution: Use verbose config view:

ralph config --verbose

Shows source of each setting (global vs project).

Next Steps

• Common Settings — Detailed explanations of each setting
• GitHub Integration — Configure GitHub authentication
• Troubleshooting — Solutions to common configuration issues