🏎️ Rrrralphy: Multi-Engine Support for Maximum Speed

[zkwentz]

Preamble

Rrrralphy goes FAST - this PR adds multi-engine support so you can run parallel agents across Claude, Cursor, OpenCode, Codex, and Q simultaneously.

• Worker pool pattern - tasks are dynamically claimed from a queue, so no engine sits idle while work remains
• Auto-detection - --multi-engine flag auto-detects and uses all available AI engines on your system
• Distribution strategies - round-robin, random, fill-first, and weighted distribution across engines
• Engine-specific metrics - track costs, tokens, and performance per-engine in final summary

Note: Requires bash v4 (mac: brew install bash).

This is experimental but has been working locally on my fork. Ready to make ralphy go rrrreally fast! 🚀

---

Summary

Adds comprehensive multi-engine support for parallel task execution, allowing Ralphy to distribute work across multiple AI engines (Claude, Codex, OpenCode, Cursor, Qwen, Droid) simultaneously.

Key Features

• Worker Pool Pattern: Tasks are dynamically claimed from a queue - when any engine finishes, it immediately grabs the next available task. No engine sits idle while work remains.
• Auto-Detection: --multi-engine flag automatically detects and uses all available AI engines on the system
• Engine Discovery: --detect-engines flag shows which engines are installed
• Manual Selection: --engines flag for explicit engine selection with optional weights (e.g., --engines claude:3,codex:1)
• Distribution Strategies: Round-robin (default), weighted, random, or fill-first distribution

New CLI Options

--multi-engine              # Auto-detect and use all available engines
--detect-engines            # Show detected engines and exit
--engines LIST              # Comma-separated engines with optional weights
--engine-distribution MODE  # round-robin, weighted, random, fill-first

Example Usage

# Auto-detect and use all available engines
./ralphy.sh --multi-engine

# Check what engines are available
./ralphy.sh --detect-engines

# Use specific engines with weights (5:1 ratio favoring Claude)
./ralphy.sh --parallel --engines claude:5,codex:1 --engine-distribution weighted

# Simple multi-engine with round-robin
./ralphy.sh --parallel --engines claude,codex,opencode

Technical Details

• Portable mkdir-based locking (works on macOS and Linux)
• Engine metrics tracking (success/failure counts, tokens, costs per engine)
• Engine assignment preview in dry-run mode
• Backward compatible with existing single-engine usage

Test plan

• --detect-engines shows available engines
• --multi-engine auto-detects and configures engines
• Worker pool dynamically claims tasks
• Engines rotate via round-robin distribution
• Dry-run shows multi-engine configuration
• Full parallel execution with multiple engines

🤖 Generated with Claude Code

[vercel]

@zkwentz is attempting to deploy a commit to the Goshen Labs Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds comprehensive multi-engine support to Ralphy, enabling parallel task execution across multiple AI engines (Claude, OpenCode, Cursor, Codex, Qwen, Droid) using a worker pool pattern.

Key Changes:

• Worker pool implementation where tasks are dynamically claimed from a queue, ensuring no engine sits idle while work remains
• Auto-detection of available AI engines via --multi-engine flag
• Support for distribution strategies: round-robin, weighted, random, and fill-first
• Engine-specific metrics tracking (costs, tokens, success/failure counts per engine)
• Serialization/deserialization of engine configuration for subshell communication (bash arrays don't propagate to subshells)
• Comprehensive test suite covering backward compatibility, parsing, distribution strategies, and metrics

Issues Found:

• get_next_engine_atomic() only implements round-robin distribution and ignores the ENGINE_DISTRIBUTION setting - weighted, random, and fill-first strategies won't work in parallel mode
• Minor: IFS modification in argument parsing (line 1260) is not restored, though impact is likely minimal

Resolved from Previous Reviews:

• All merge conflicts have been resolved
• ENGINE_WEIGHTS properly reset between tests using unset and declare -A
• Unset array key checks now use :- pattern to avoid errors
• IFS properly restored in test files

The implementation is well-structured with excellent documentation and test coverage. The worker pool pattern is a solid design choice for dynamic task distribution. The main blocker is the distribution strategy bug in the worker pool.

Confidence Score: 3/5

• This PR has significant functionality but contains a critical bug in engine distribution that prevents non-round-robin strategies from working in parallel mode
• Score of 3 reflects: (1) excellent test coverage and documentation, (2) all previous review issues resolved, (3) well-designed worker pool architecture, BUT (4) critical bug where get_next_engine_atomic() ignores ENGINE_DISTRIBUTION setting, making weighted/random/fill-first strategies non-functional in parallel mode - this is a core feature that doesn't work as advertised
• Pay close attention to ralphy.sh line 2884-2918 - the get_next_engine_atomic() function needs to implement all distribution strategies, not just round-robin

Important Files Changed

Filename	Overview
ralphy.sh	Major multi-engine implementation with worker pool pattern, but get_next_engine_atomic ignores ENGINE_DISTRIBUTION setting
test_backward_compatibility.sh	Merge conflicts resolved - comprehensive backward compatibility tests
test_weighted_distribution.sh	Proper ENGINE_WEIGHTS reset between tests - comprehensive weighted distribution test coverage
test_get_engine_for_agent.sh	Merge conflicts resolved - tests engine assignment logic for different distribution strategies
test_engines_parsing.sh	IFS properly restored - validates engine specification parsing with weights
docs/multi-engine-spec.md	Comprehensive documentation for multi-engine feature with architecture details and examples

Sequence Diagram

sequenceDiagram
    participant User
    participant Main as ralphy.sh (main)
    participant Queue as Task Queue
    participant W1 as Worker 1
    participant W2 as Worker 2
    participant W3 as Worker 3
    participant Engine1 as Claude
    participant Engine2 as OpenCode
    participant Engine3 as Cursor

    User->>Main: ./ralphy.sh --multi-engine --parallel
    Main->>Main: detect_available_engines()
    Main->>Main: serialize_engine_config()
    Main->>Queue: task_queue_init(tasks)
    Main->>Queue: Write all tasks to queue file
    
    par Spawn Workers
        Main->>W1: run_worker(1) &
        Main->>W2: run_worker(2) &
        Main->>W3: run_worker(3) &
    end
    
    W1->>W1: deserialize_engine_config()
    W2->>W2: deserialize_engine_config()
    W3->>W3: deserialize_engine_config()
    
    loop Worker Pool Pattern
        W1->>Queue: task_queue_claim() [atomic lock]
        Queue-->>W1: Task A
        W1->>W1: get_next_engine_atomic()
        W1->>Engine1: run_parallel_agent(Task A, claude)
        
        W2->>Queue: task_queue_claim() [atomic lock]
        Queue-->>W2: Task B
        W2->>W2: get_next_engine_atomic()
        W2->>Engine2: run_parallel_agent(Task B, opencode)
        
        W3->>Queue: task_queue_claim() [atomic lock]
        Queue-->>W3: Task C
        W3->>W3: get_next_engine_atomic()
        W3->>Engine3: run_parallel_agent(Task C, cursor)
        
        Engine1-->>W1: Result (success/failure)
        W1->>Queue: Store result file
        
        W1->>Queue: task_queue_claim() [next task]
        Queue-->>W1: Task D
        W1->>Engine1: run_parallel_agent(Task D, claude)
        
        Engine2-->>W2: Result
        W2->>Queue: Store result file
        W2->>Queue: task_queue_claim()
        Queue-->>W2: (empty - exit)
        
        Engine3-->>W3: Result
        W3->>Queue: Store result file
        W3->>Queue: task_queue_claim()
        Queue-->>W3: Task E
    end
    
    Main->>Main: Monitor worker_pids (wait)
    Main->>Queue: Collect all result files
    Main->>Main: print_engine_summary()
    Main-->>User: Multi-engine execution complete

Loading

[greptile-apps]

_{31 files reviewed, 14 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

syntax: Comment mentions 'negative' but test description says 'zero' - should clarify which invalid weight case this tests

Prompt To Fix With AI

This is a comment left during a code review.
Path: test_error_messages.sh
Line: 44:44

Comment:
**syntax:** Comment mentions 'negative' but test description says 'zero' - should clarify which invalid weight case this tests

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

logic: Test 5 overwrites the claude and opencode data from previous tests, which could mask issues if the function doesn't handle data updates correctly.

Prompt To Fix With AI

This is a comment left during a code review.
Path: test_print_engine_summary.sh
Line: 86:94

Comment:
**logic:** Test 5 overwrites the claude and opencode data from previous tests, which could mask issues if the function doesn't handle data updates correctly.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

syntax: syntax error in conditional structure - missing 'fi' to close the if statement started on line 4154

Suggested change

	if [[ ${#ENGINES[@]} -eq 0 ]] && [[ "$MULTI_ENGINE" != true ]]; then
	ENGINES=("$AI_ENGINE")
	# Load browser setting from config (if not overridden by CLI flag)
	if [[ "$BROWSER_ENABLED" == "auto" ]] && [[ -f "$CONFIG_FILE" ]]; then
	BROWSER_ENABLED=$(load_browser_setting)
	fi
	# Backward compatibility: populate ENGINES if not set
	# Skip if using --multi-engine (it will auto-detect)
	if [[ ${#ENGINES[@]} -eq 0 ]] && [[ "$MULTI_ENGINE" != true ]]; then
	ENGINES=("$AI_ENGINE")
	fi
	# Load browser setting from config (if not overridden by CLI flag)
	if [[ "$BROWSER_ENABLED" == "auto" ]] && [[ -f "$CONFIG_FILE" ]]; then
	BROWSER_ENABLED=$(load_browser_setting)
	fi

Prompt To Fix With AI

This is a comment left during a code review.
Path: ralphy.sh
Line: 4154:4161

Comment:
**syntax:** syntax error in conditional structure - missing 'fi' to close the if statement started on line 4154

```suggestion
  # Backward compatibility: populate ENGINES if not set
  # Skip if using --multi-engine (it will auto-detect)
  if [[ ${#ENGINES[@]} -eq 0 ]] && [[ "$MULTI_ENGINE" != true ]]; then
    ENGINES=("$AI_ENGINE")
  fi

  # Load browser setting from config (if not overridden by CLI flag)
  if [[ "$BROWSER_ENABLED" == "auto" ]] && [[ -f "$CONFIG_FILE" ]]; then
    BROWSER_ENABLED=$(load_browser_setting)
  fi
```

How can I resolve this? If you propose a fix, please make it concise.

[zkwentz]

@greptile give it another look please

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[michaelshimeles]

Going to review this in the AM. Good stuff @zkwentz

[emkman]

I'd love a variation on this where I can use an engine like Claude Code and then once I hit my daily usage limit I can specify a failover engine to switch to GLM in OpenCode, for example

[zkwentz]

That was sort of the spirit behind this. In practice this pool approach isn't working all that well due to merge conflicts and need for isolated tasks.

I'd be fine to rework this in the spirit of quota conservation which was original goal anyway.

The only thing I can see being practical here is a sort of cheap multi engine approach with expensive overseer taking best implementation from the group (i.e. GRPO applied to test time).

Probably worth landing the conservation first, and consensus second using this as starting point but ultimately abandoning this one but for key functionality.

[emkman]

Makes sense. I was definitely thinking of simple failover more than pooling. Quota conservation to avoid hitting the limit is also interesting but may also be more complicated than necessary,

[michaelshimeles]

@greptile review

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

get_next_engine_atomic() only implements round-robin distribution and ignores the ENGINE_DISTRIBUTION setting. When users specify --engine-distribution weighted, random, or fill-first, the worker pool will still use round-robin.

The function should check ENGINE_DISTRIBUTION and implement the selected strategy atomically, similar to how get_engine_for_agent() does it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: ralphy.sh
Line: 2884:2918

Comment:
`get_next_engine_atomic()` only implements round-robin distribution and ignores the `ENGINE_DISTRIBUTION` setting. When users specify `--engine-distribution weighted`, `random`, or `fill-first`, the worker pool will still use round-robin.

The function should check `ENGINE_DISTRIBUTION` and implement the selected strategy atomically, similar to how `get_engine_for_agent()` does it.

How can I resolve this? If you propose a fix, please make it concise.