DEV Community

Levi
Levi

Posted on

I Let 5 AI Agents Loose on One Repo. It Was a Disaster. So I Built This.

#ai #productivity #programming #opensource

Last month I tried something ambitious: split a feature across five AI coding agents running in parallel. Claude Code on auth. Aider on the API. Codex on tests. Two more on frontend components.

Within 90 seconds, three of them had edited src/index.ts. Two had conflicting changes to the same utility function. One had deleted a file another was importing.

The merge was unfixable. I lost an hour untangling it, then threw everything away and did it sequentially. One agent at a time. Like it's 2024.

That experience broke something in my brain. AI agents are fast enough to work in parallel — but our tooling assumes they work alone. So I built the missing piece.

The Problem Nobody Talks About

Every AI coding tool — Claude Code, Cursor, Aider, Codex, Windsurf — operates with a mental model of "one agent, one repo." And that's fine for solo tasks.

But the moment you want parallelism — the thing that should make AI 5x faster — you hit the wall:

  • No workspace isolation. Agents share a checkout. One agent's git stash nukes another's work.
  • No file ownership. Two agents rewrite the same module with zero awareness of each other.
  • No merge strategy. You're the merge strategy. At 2am. With conflicting diffs you didn't write.
  • No dependency ordering. The frontend agent starts before the API it depends on exists.

Git branches help with history isolation. But branches don't prevent two agents from touching the same files. They just defer the pain to merge time.

Ruah Orch: Parallel Agents That Don't Collide

Ruah Orch is an open-source orchestration engine that coordinates multiple AI agents working on the same repository. Each task gets:

1. An isolated workspace (Git worktree — a real checkout, not a branch)

ruah task create auth --files "src/auth/**" --executor claude-code
ruah task create api  --files "src/api/**"  --executor aider
ruah task create ui   --files "src/ui/**"   --executor claude-code
Enter fullscreen mode Exit fullscreen mode

2. File locks checked before agents start

ruah task create utils --files "src/utils/**"
# ERROR: Lock conflict with task 'auth' on src/utils/helpers.ts
Enter fullscreen mode Exit fullscreen mode

No more discovering conflicts after an agent has been running for 10 minutes. Ruah rejects overlapping file claims at creation time.

3. Smart parallel execution with dependency ordering

# workflow.md

backend:
  files: src/api/**
  executor: claude-code
  prompt: "Build REST endpoints for user management"

frontend:
  files: src/ui/**
  executor: claude-code
  parallel: true
  prompt: "Build user profile components"

integration-tests:
  files: tests/**
  depends: [backend, frontend]
  executor: aider
  prompt: "Write integration tests for the user flow"
Enter fullscreen mode Exit fullscreen mode 
ruah workflow run workflow.md
Enter fullscreen mode Exit fullscreen mode

Ruah builds a DAG, validates there are no cycles, checks for file conflicts, then runs backend and frontend in parallel. integration-tests waits until both are done.

4. Contract enforcement before merge

Tasks can declare modification contracts:

  • owned — only this task touches these files
  • shared-append — append only, no deletions
  • read-only — hands off

Violations are caught before merge, not after.

It Works With Everything

Ruah isn't tied to one AI tool. It ships with executor adapters for:

Executor Tool
claude-code Claude Code CLI
aider Aider
codex OpenAI Codex CLI
script Any shell command

Mix and match. Use Claude Code for complex architecture and Aider for quick edits. Ruah doesn't care — it manages workspaces, not agents.

ruah task create backend --executor claude-code --prompt "Design the auth system"
ruah task create docs    --executor aider        --prompt "Write API documentation"
ruah task create tests   --executor codex        --prompt "Add unit test coverage"
Enter fullscreen mode Exit fullscreen mode

The 5-Minute Version 

# Install
npm install -g @ruah-dev/orch

# Initialize in your repo
cd your-project
ruah init

# Create parallel tasks with file isolation
ruah task create auth    --files "src/auth/**"    --executor claude-code
ruah task create payments --files "src/payments/**" --executor claude-code

# Start them (each gets its own worktree)
ruah task start auth
ruah task start payments

# When done, merge cleanly
ruah task done auth
ruah task merge auth

ruah task done payments
ruah task merge payments
Enter fullscreen mode Exit fullscreen mode

That's it. Two agents, working in parallel, zero collisions, clean merges.

What Happens Under the Hood

When you run ruah task start auth:

  1. Worktree created — A real Git worktree at .ruah/worktrees/auth/, branched from your current HEAD
  2. Locks acquired — src/auth/** is claimed. No other task can touch these files
  3. Environment injected — The agent receives RUAH_TASK, RUAH_WORKTREE, RUAH_FILES, RUAH_ROOT
  4. Executor launched — Claude Code (or Aider, or your script) starts in the isolated worktree
  5. Artifacts captured — Changed files, patches, and commit metadata are persisted to .ruah/state.json

When you ruah task merge auth:

  1. Contracts validated — Did the agent stay within its file boundaries?
  2. Governance gates run — If you have quality gates (linting, tests, type checking), they run automatically
  3. Clean merge — Changes merge into your base branch. No surprises.

Subtasks: Agents Spawning Agents

Here's where it gets interesting. A parent task can spawn child tasks:

ruah task create auth-api --parent auth --files "src/auth/api/**"
ruah task create auth-ui  --parent auth --files "src/auth/ui/**"
Enter fullscreen mode Exit fullscreen mode

Children branch from the parent (not main), inherit its context, and merge back into the parent. The parent then merges into main. It's turtles all the way down — but organized turtles.

Zero Dependencies. Zero Network. Zero Risk.

Ruah has zero runtime dependencies. The node_modules after install? Just dev tools. The binary is pure TypeScript compiled to ESM.

  • No network calls (unless you explicitly opt into update checks)
  • No secrets stored
  • No shell injection risk (array-form process spawning)
  • MIT licensed

Your code never leaves your machine. Ruah just manages workspaces and state.

Built-in Safety Net 

# Health check everything
ruah doctor

# See what's running
ruah status

# Clean up stale tasks and orphaned worktrees
ruah clean

# Preview a workflow without executing
ruah workflow run plan.md --dry-run
Enter fullscreen mode Exit fullscreen mode

When Should You Use This?

Use Ruah when:

  • You're splitting features across multiple AI agents
  • You want parallelism without merge hell
  • You use more than one AI coding tool
  • Your team has AI agents running on shared repos
  • You're building agentic workflows that decompose tasks

Don't use Ruah when:

  • You're running a single agent on a single task (just use the agent directly)
  • Your changes are all in one file (no isolation needed)

What's Next

Ruah Orch is Phase 1. The orchestration layer. Coming next:

  • Ruah Architect — Feed it a PRD or GitHub issue, get a parallelized workflow back
  • Ruah Guard — Policy engine for what agents can and can't do
  • Ruah Observe — Tracing and observability for multi-agent runs
  • Ruah Studio — Visual UI for watching agents work in real-time

But Orch is shipping now, it's stable, and it solves the #1 pain point: agents that don't step on each other.

npm install -g @ruah-dev/orch
Enter fullscreen mode Exit fullscreen mode

GitHub | npm

If you've felt the pain of merging parallel AI agent work, give it a try. Stars welcome. Issues more welcome. PRs most welcome.

Have you tried running multiple AI agents in parallel? What was your experience? Drop a comment — I'd love to hear your war stories.

Top comments (0)