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

Levi — Fri, 10 Apr 2026 19:46:48 +0000

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

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

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"

ruah workflow run workflow.md

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"

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

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

What Happens Under the Hood

When you run ruah task start auth:

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

When you ruah task merge auth:

Contracts validated — Did the agent stay within its file boundaries?
Governance gates run — If you have quality gates (linting, tests, type checking), they run automatically
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/**"

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

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

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.

DEV Community: Levi