ralph-parallel: Orchestrating Concurrent AI Agents for Parallel Code Execution

Hook

What if you could run eight AI coding agents simultaneously on different parts of your codebase without them stepping on each other's toes? One developer built exactly that—and achieved a 3.4x speedup on real-world specifications.

Context

The evolution of AI-assisted development has reached an inflection point. We've moved beyond simple autocomplete and chat interfaces to autonomous agents that can implement entire features. Claude Code's Agent Teams feature represents this frontier: spawn multiple AI teammates, assign them work, and theoretically multiply your development throughput.

But theory collides with practice when those agents need coordination. Without orchestration, you face race conditions, merge conflicts, broken tests, and agents that overwrite each other's changes. The promise of parallel AI development requires sophisticated traffic control—determining which tasks can run concurrently, enforcing file ownership boundaries, maintaining code quality through checkpoints, and handling the inevitable session crashes when agents disconnect mid-work. ralph-parallel emerged from this coordination gap: a plugin that transforms Agent Teams from a manual coordination nightmare into an automated parallel execution engine, specifically designed to work with ralph-specum task specifications.

Technical Insight

At its core, ralph-parallel is a dependency graph builder and task dispatcher. It ingests specifications from ralph-specum (a separate tool that generates structured task definitions), analyzes file ownership patterns, constructs a directed acyclic graph of dependencies, and assigns work to AI teammates based on what can execute concurrently without conflicts.

The architecture revolves around three key mechanisms: isolation enforcement, quality gates, and coordinator ownership. Let's examine each.

Isolation Through File Ownership

The plugin implements two strategies for preventing agents from interfering with each other. The default file-ownership strategy assigns specific files to specific teammates and enforces boundaries through PreToolUse hooks—intercepting every file write operation before it executes:

# Conceptual representation of the PreToolUse enforcement
def pre_tool_use_hook(teammate_id, tool_call):
    if tool_call.tool == "write_file":
        target_file = tool_call.args["path"]
        owned_files = get_ownership_map()[teammate_id]
        
        if target_file not in owned_files:
            raise IsolationViolation(
                f"Teammate {teammate_id} attempted to write {target_file} "
                f"but only owns: {owned_files}"
            )
    
    # Allow operation to proceed if ownership check passes
    return tool_call

This runtime enforcement prevents race conditions at the source. If Task A modifies src/auth.py and Task B tries to touch the same file, the hook blocks the operation immediately. The alternative worktree strategy takes isolation further by giving each teammate a separate git worktree—completely independent working directories—but requires a merge step afterward that can introduce conflict resolution overhead.

Six-Stage Quality Gate Pipeline

Parallel execution is worthless if agents break the codebase. ralph-parallel implements a verification pipeline that runs after each task completion:

# Quality gate stages (executed in sequence)
1. Run test suite
2. Check test count regression (must be ≥90% of baseline)
3. Run type checker (mypy/pyright)
4. Execute build process
5. Run linter checks
6. Verify git status clean

The test regression detection is particularly clever. Many AI agents will "fix" failing tests by deleting them or skipping them—technically making tests pass but reducing coverage. By tracking the baseline test count and blocking any task that drops below 90% of that number, the plugin catches this failure mode. A teammate that tries to merge a change that went from 150 tests to 120 tests gets rejected, forcing the agent to find the real fix.

Session-Aware Coordinator Ownership

Claude Code sessions crash. It's not a question of if, but when. ralph-parallel handles this with a heartbeat-based ownership system. The coordinator process (the main plugin instance) maintains a lock file with timestamps:

# Simplified coordinator ownership logic
class CoordinatorOwnership:
    def __init__(self, heartbeat_threshold=600):  # 10 minutes
        self.lock_file = ".ralph-parallel/coordinator.lock"
        self.heartbeat_threshold = heartbeat_threshold
    
    def acquire_ownership(self):
        if self.lock_file.exists():
            last_heartbeat = self.read_heartbeat()
            time_since_heartbeat = now() - last_heartbeat
            
            if time_since_heartbeat > self.heartbeat_threshold:
                # Previous coordinator is dead, reclaim ownership
                self.write_heartbeat()
                return True
            else:
                # Active coordinator exists, back off
                return False
        
        # No existing coordinator, claim ownership
        self.write_heartbeat()
        return True
    
    def maintain_heartbeat(self):
        while self.is_running:
            self.write_heartbeat()
            sleep(60)  # Update every minute

When a Claude session dies mid-execution, its heartbeat stops updating. After 10 minutes of silence, any new session running ralph-parallel can safely reclaim coordinator ownership and resume the parallel execution from where it left off. This design prevents multiple coordinators from spawning competing teammates while enabling graceful recovery from crashes.

Dependency Graph and Partitioning

The reason ralph-parallel achieves 3.4x speedup (validated across 80+ tasks in real specifications) is intelligent task partitioning. The plugin parses each task's file dependencies from the ralph-specum specification, builds a graph where edges represent "must complete before" relationships, and identifies maximal independent sets—groups of tasks with no interdependencies that can run simultaneously.

Consider a specification with 24 tasks split across frontend, backend, and database work. Traditional sequential execution takes 24 time units. With ralph-parallel's analysis:

• Frontend tasks (8) touch only src/ui/* files
• Backend tasks (12) touch only src/api/* and src/services/* files
• Database tasks (4) touch only migration files and src/models/*

These three groups have zero file overlap. The plugin spawns three teammates, executes all groups concurrently, and completes in roughly 12 time units (the duration of the longest group) plus quality gate overhead. The 3.4x speedup reflects this parallelism minus coordination costs.

The plugin caps teammates at 8 maximum—a practical limit based on Claude Code's API constraints and the cognitive overhead of monitoring multiple agent outputs. Beyond 8, the marginal benefit diminishes as coordination overhead and context-switching costs dominate any parallelism gains.

Gotcha

The file ownership strategy, while preventing race conditions elegantly, has a dark side: it serializes work on shared files. If your specification includes 15 tasks that all modify src/config.py for different configuration additions, ralph-parallel will execute them sequentially despite the potential for intelligent merge strategies. The plugin prioritizes safety over theoretical maximum parallelism, which is the right trade-off for production codebases but means you won't see linear scaling with teammate count.

The worktree strategy solves this by giving each teammate full file access in isolation, but introduces its own pain: merge conflicts. After parallel execution completes, you face a manual merge step where conflicts must be resolved by hand (or by prompting Claude to resolve them, which works with varying success). On smaller specifications—say, under 10 tasks—the coordination overhead of spawning teammates, running quality gates, and merging worktrees often exceeds the time savings from parallelism. The 3.4x speedup only manifests on larger, well-structured specifications where natural task boundaries exist.

The tight coupling to ralph-specum is another limitation. You cannot use ralph-parallel as a standalone orchestration tool for arbitrary parallel work. It expects a specific task specification format with file dependencies explicitly declared. If you're not already in the ralph-specum ecosystem for specification management, adopting ralph-parallel requires learning and integrating both tools, which represents significant upfront investment for uncertain payoff.

Verdict

Use if: You're working with large feature specifications (20+ tasks) that have clear file boundaries, already using ralph-specum for task specification, and operating in codebases with good separation of concerns where tasks naturally partition into independent work units. The 3.4x speedup is real when conditions align—particularly valuable for implementing sprawling features across frontend, backend, and infrastructure where different agents can own different layers. Also use if you value the quality gate enforcement even without parallelism, as the 6-stage pipeline catches common AI agent failure modes like test deletion and build breaks.

Skip if: Your specifications are small (under 10 tasks), your codebase is highly coupled with most tasks touching shared files, or you're not already invested in the ralph-specum tooling. The coordination overhead makes this overkill for quick feature additions or bug fixes. Also skip if you need flexibility in orchestration—the plugin is opinionated about workflow and doesn't offer escape hatches for custom coordination strategies. For ad-hoc parallel work or codebases without clear module boundaries, manual Agent Teams usage or traditional sequential AI assistance will be more productive.