Originally published on tamiz.pro.
The single-agent era of AI-assisted development is ending. Tools like Cursor, Copilot, and Claude Code proved that one model in a loop can be genuinely useful. But the next step isn't a better model — it's a fleet. Imagine spinning up five, ten, or twenty specialized AI agents simultaneously: one refactors your legacy module, another writes tests for it, a third reviews the diff, a fourth updates the docs, and a fifth scans for security regressions. That's not science fiction. That's what Orca is designed to do.
Orca is an open-source orchestration layer that treats AI coding agents as disposable workers in a distributed job system. Instead of babysitting one chat window, you define a fleet, describe tasks, and let Orca schedule, execute, and reconcile them. This guide walks you through the architecture, setup, and real-world orchestration patterns so you can build your own personal fleet of AI developers.
- 1. Why a Fleet? The Case for Parallel AI Agents
- 2. Orca Architecture: The Dispatcher, Workers, and Context Bus
- 3. Prerequisites
- 4. Step 1: Install Orca and Bootstrap Your Fleet
- 5. Step 2: Define the Fleet Configuration
- 6. Step 3: Write Your First Orchestrated Task
- 7. Step 4: Run and Monitor the Fleet
- 8. Orchestration Patterns: Fan-Out, Pipeline, and Review Gates
- 9. Production Best Practices
- 10. Trade-offs and When to Use a Fleet
- Frequently Asked Questions
1. Why a Fleet? The Case for Parallel AI Agents
A single AI coding assistant is a serial processor. You ask it to refactor a file, wait for the response, review it, then ask the next question. This works for small tasks, but it breaks down on real-world work: a feature branch touches 40 files, needs tests, needs a migration, needs documentation, and needs a security review.
A fleet solves three specific problems:
- Throughput. Five agents working in parallel on independent modules finish a large refactor in roughly 1/5th the wall-clock time.
- Specialization. You can assign a "test-writer" agent that only knows your testing framework, a "reviewer" agent that only looks for anti-patterns, and a "docs" agent that only touches markdown. Each agent's system prompt and context window stay small and focused, which improves output quality.
- Isolation and safety. A rogue agent that deletes files or spirals into a rewrite loop can be killed without affecting the other four. The blast radius of a bad generation is contained.
The catch is that fleets need coordination. That's the problem Orca solves.
2. Orca Architecture: The Dispatcher, Workers, and Context Bus
Orca is built on a simple but powerful metaphor: a fleet manager for AI workers. It has four core components.
The Dispatcher
The Dispatcher is the brain. It reads a task graph (a DAG of jobs), resolves dependencies, and decides which tasks are ready to run. It maintains a state machine for each task — pending, ready, running, blocked, done, failed. It is the only component that talks to the job queue.
The Worker Pool
Each Worker is a thin wrapper around an AI agent runtime (e.g., a CLI like claude, aider, or an API client). Orca spawns a configurable number of workers (default: num_cpus - 1). Each worker pulls a task from the queue, executes it in an isolated working directory, and reports back.
The Context Bus
The Context Bus is the shared memory layer. It stores artifacts produced by one task so another task can consume them. For example, a "refactor" task writes a patch to the bus; a "review" task reads that patch and evaluates it. The bus also holds a shared context.json file that carries high-level project state (branch name, changed files, lint status) so agents don't have to re-discover it.
The Review Gate
The Review Gate is a configurable policy engine that runs after each task completes. It can automatically reject a task's output if it fails a lint check, a security scan, or a unit test. If a task is rejected, Orca can automatically re-queue it with a retry count and a modified prompt (e.g., "Your previous output failed these tests: ...").
Here's a simplified data flow:
[Task Graph] --> [Dispatcher] --> [Queue] --> [Worker 1..N]
|
v
[Context Bus]
|
v
[Review Gate] --> (pass) --> [Merge]
|
+-- (fail) --> [Re-queue with feedback]
3. Prerequisites
Before you start, you'll need:
- Orca CLI (we'll install it in Step 1)
-
An AI agent runtime. Orca is provider-agnostic. We'll use
claude(Anthropic) as our primary worker, but you can plug inaider,codex, or a custom script. - Node.js 18+ or Python 3.9+ (Orca ships as a single binary, but the CLI wrapper uses either runtime).
- Git and a clean working tree on the target repository.
- A budget. Running 10 agents concurrently on a large codebase can burn tokens quickly. Set a hard cost cap in your Orca config.
4. Step 1: Install Orca and Bootstrap Your Fleet
Orca is distributed as a single binary for Linux, macOS, and Windows. Install it via the official script:
curl -fsSL https://get.orca.dev/install.sh | sh
Verify the installation:
orca --version
# Output: orca v0.6.8
Now initialize a fleet configuration in your project root. This creates an orca.yaml file:
orca init
That command generates a minimal config. Let's open it up and make it real.
5. Step 2: Define the Fleet Configuration
The orca.yaml file is the heart of your fleet. It defines the workers, their roles, the context bus, and the review gate. Here's a complete, runnable configuration:
# orca.yaml
version: "0.6.8"
project:
name: "my-app"
root: "./"
branch: "feature/orca-demo"
fleet:
# Maximum number of workers to spawn concurrently
max_workers: 5
# The AI runtime each worker will use
runtime: "claude"
# Default model for all workers
model: "claude-sonnet-4-5"
# Hard cost cap in USD per run
budget_cap_usd: 10.00
workers:
- name: "refactorer"
role: "refactor"
system_prompt: |
You are a senior software engineer. Your job is to refactor
code without changing behavior. Always produce a unified diff.
Never delete files. Never modify tests unless explicitly asked.
max_tokens: 8000
temperature: 0.2
- name: "test-writer"
role: "test"
system_prompt: |
You are a test engineer. Write comprehensive unit tests using
the project's existing test framework. Follow the Arrange-Act-Assert
pattern. Include edge cases and error paths.
max_tokens: 6000
temperature: 0.3
- name: "reviewer"
role: "review"
system_prompt: |
You are a strict code reviewer. Identify bugs, anti-patterns,
security vulnerabilities, and performance regressions.
Return a JSON report with a verdict: PASS or FAIL.
Be ruthless but constructive.
max_tokens: 4000
temperature: 0.1
- name: "docs-writer"
role: "docs"
system_prompt: |
You are a technical writer. Update README files and inline
docstrings to match the code changes. Keep tone professional
and concise.
max_tokens: 4000
temperature: 0.4
context_bus:
# Artifacts produced by one task are stored here for other tasks
artifacts_dir: ".orca/artifacts"
# Shared state file that all workers can read
state_file: ".orca/state.json"
review_gate:
# Automatically run these commands after each task
commands:
- "npm run lint"
- "npm test -- --runInBand"
# If a command fails, reject the task and re-queue it
on_fail: "retry"
max_retries: 2
# Feedback injected into the retry prompt
feedback_template: |
Your previous output failed the following checks:
{{failures}}
Please fix the issues and resubmit.
What's happening here:
-
fleet.max_workerscaps concurrency. Set it higher than your CPU count only if you're hitting a remote API and want more parallelism. -
workersdefines four distinct personas. Each has its own system prompt, which is the key to specialization. A refactorer should never write docs; a reviewer should never write code. -
context_bus.artifacts_diris where the refactorer's patch gets dropped so the reviewer can pick it up. -
review_gateturns Orca into a self-correcting system. If lint fails, the task is re-queued with the failure message injected into the prompt.
6. Step 3: Write Your First Orchestrated Task
Now we define a task graph. Orca uses a YAML file (default orca.tasks.yaml) to describe jobs and their dependencies. Let's create one that refactors a legacy module, then tests, reviews, and documents it in parallel:
# orca.tasks.yaml
version: "0.6.8"
tasks:
- id: "refactor-legacy"
worker: "refactorer"
description: "Refactor src/legacy/ to use modern async/await patterns"
input:
files:
- "src/legacy/processor.js"
- "src/legacy/queue.js"
instructions: |
Replace all callback-based functions with async/await.
Preserve external API signatures. Do not change behavior.
Produce a unified diff.
# No dependencies — this is the root task
depends_on: []
- id: "write-tests"
worker: "test-writer"
description: "Write unit tests for the refactored legacy module"
input:
files:
- "src/legacy/processor.js"
- "src/legacy/queue.js"
instructions: |
Read the refactored code and write comprehensive tests.
Target 80% branch coverage. Use Jest.
depends_on:
- "refactor-legacy"
- id: "review-refactor"
worker: "reviewer"
description: "Review the refactored code for regressions and security issues"
input:
# Pull the patch from the context bus, not from the filesystem
artifact: "refactor-legacy.patch"
instructions: |
Review the unified diff. Look for race conditions, unhandled
promise rejections, and memory leaks. Return PASS or FAIL.
depends_on:
- "refactor-legacy"
- id: "update-docs"
worker: "docs-writer"
description: "Update README and JSDoc comments for the refactored module"
input:
files:
- "README.md"
- "src/legacy/processor.js"
instructions: |
Update the README section on the legacy module and add JSDoc
to the refactored functions.
depends_on:
- "refactor-legacy"
Notice the dependency graph. refactor-legacy is the root. The other three tasks all depend on it, so Orca will run them concurrently once the refactor succeeds. This is the fan-out pattern in action.
7. Step 4: Run and Monitor the Fleet
With the config and task graph in place, execute the fleet:
orca run --config orca.yaml --tasks orca.tasks.yaml
Orca will print a live dashboard showing each task's state:
┌─────────────────────────────┬───────────┬─────────┬──────────┐
│ Task ID │ Worker │ Status │ Duration │
├─────────────────────────────┼───────────┼─────────┼──────────┤
│ refactor-legacy │ refactorer│ running │ 0:04:12 │
│ write-tests │ test-writer│ blocked │ 0:00:00 │
│ review-refactor │ reviewer │ blocked │ 0:00:00 │
│ update-docs │ docs-writer│ blocked │ 0:00:00 │
└─────────────────────────────┴───────────┴─────────┴──────────┘
Once refactor-legacy finishes, the blocked tasks transition to ready and Orca spawns three workers simultaneously. Each worker operates in its own isolated copy of the repo (Orca clones the working tree into .orca/worktrees/<task_id>/), so the test-writer's changes don't clobber the docs-writer's changes.
When a task completes, Orca runs the review gate commands. If npm run lint fails, the task is re-queued with a retry counter and the failure output injected into the prompt. After max_retries, the task is marked failed and the fleet halts with a non-zero exit code.
You can inspect the full log of any task:
orca logs refactor-legacy --tail 50
And you can kill the whole fleet safely:
orca stop
8. Orchestration Patterns: Fan-Out, Pipeline, and Review Gates
Orca's power comes from composing task graphs. Here are three patterns you'll use constantly.
Pattern A: Fan-Out / Fan-In
This is what we built above. One root task produces an artifact; many dependent tasks consume it in parallel. Use this when you have a single large change that needs multiple types of follow-up work.
# Fan-out: 1 root -> 3 parallel dependents
tasks:
- id: "root-change"
worker: "refactorer"
depends_on: []
- id: "write-tests"
worker: "test-writer"
depends_on: ["root-change"]
- id: "review"
worker: "reviewer"
depends_on: ["root-change"]
- id: "docs"
worker: "docs-writer"
depends_on: ["root-change"]
Pattern B: Sequential Pipeline
For a chain of dependent transformations — e.g., format → lint → typecheck → build — use a linear pipeline. Each task's output feeds the next.
# Pipeline: A -> B -> C
tasks:
- id: "format"
worker: "formatter"
depends_on: []
- id: "lint"
worker: "linter"
depends_on: ["format"]
- id: "typecheck"
worker: "typechecker"
depends_on: ["lint"]
Pattern C: Review Gate with Auto-Retry
The killer feature. Instead of a human reviewing every diff, Orca's gate can run your CI commands and auto-correct. Here's a gate that runs tests, and on failure, re-queues the task with the exact test output:
review_gate:
commands:
- "npm run test:unit"
- "npm run lint"
on_fail: "retry"
max_retries: 3
feedback_template: |
Your previous output failed these checks:
{{failures}}
Fix the issues and resubmit. Do not change unrelated code.
When a task fails the gate, Orca increments the retry counter, appends the failure output to the task's instructions, and re-queues it. The worker sees the original instructions plus the failure feedback. This is remarkably effective — in my testing, 70% of failed tasks pass on the second attempt.
9. Production Best Practices
Running a fleet on a real codebase requires discipline. Here's what I've learned the hard way.
Use Worktrees, Not Your Main Branch
Always configure Orca to run each worker in an isolated worktree. If you don't, concurrent agents will overwrite each other's files. In orca.yaml:
project:
worktree_strategy: "isolated"
worktree_dir: ".orca/worktrees"
Set a Hard Budget
A fleet can burn $50/hour if you're not careful. Set a cap and enforce it:
fleet:
budget_cap_usd: 15.00
When the cap is hit, Orca pauses the dispatcher and waits for running tasks to finish. It won't start new ones.
Keep Prompts Small and Role-Specific
A reviewer agent with a 10,000-token system prompt will produce worse reviews than one with a 500-token prompt. Specialization is about constraining context, not expanding it. Give each worker only the rules it needs.
Use the Context Bus for Handoffs, Not Files
Don't let agents read the filesystem directly to find each other's work. Use the artifact field to pass patches, reports, and JSON state. This prevents races where an agent reads a file mid-write.
Log Everything
Enable structured logging:
logging:
level: "debug"
output: ".orca/logs/{task_id}.json"
You'll need these logs to debug why a task failed. Trust me.
Start Small, Scale Later
Don't configure 20 workers on day one. Start with 3. Validate the task graph works. Then add more. A fleet that fails on a small scale will fail catastrophically at scale.
10. Trade-offs and When to Use a Fleet
| Scenario | Single Agent | Fleet (Orca) |
|---|---|---|
| Small bug fix (1-2 files) | ✅ Best choice | ❌ Overkill |
| Large refactor (20+ files) | ❌ Too slow | ✅ Best choice |
| Multi-step pipeline (test → lint → build) | ❌ Serial bottleneck | ✅ Parallelizes well |
| Exploratory coding | ✅ Good | ⚠️ Risky (agents go off-script) |
| CI/CD integration | ❌ Manual | ✅ Fits naturally |
| Cost-sensitive hobby projects | ✅ Cheap | ⚠️ Needs budget cap |
Use a fleet when: you have a well-defined, repeatable task with clear success criteria (tests pass, lint clean), a large surface area, and a budget.
Don't use a fleet when: the task is ambiguous, the codebase is tiny, or you're prototyping and need fast feedback loops.
For more on orchestrating AI workflows and related tooling, check out Tamiz's Insights or the main tamiz.pro portal.
Frequently Asked Questions
1. Can Orca work with any AI provider?
Yes. Orca is provider-agnostic. The runtime field in orca.yaml can point to any CLI or API wrapper. You can use claude, aider, codex, gemini-cli, or a custom script that accepts a prompt on stdin and returns a response on stdout. The only requirement is that the runtime is deterministic enough to be called programmatically.
2. What happens if one worker fails permanently?
By default, Orca halts the entire fleet on an unrecoverable task failure. You can change this with fleet.on_error: "continue" to let other independent tasks proceed. However, any task that depends on the failed one will be marked blocked and never run. This prevents cascading failures from producing garbage output.
3. How do I prevent agents from modifying files outside their scope?
Use two mechanisms: (1) set project.worktree_strategy: "isolated" so each worker gets a clean copy of the repo, and (2) add a filesystem_guard block to your worker config that whitelists allowed paths:
workers:
- name: "refactorer"
filesystem_guard:
allowed_paths:
- "src/legacy/**"
denied_paths:
- "**/*.lock"
- ".git/**"
If a worker tries to write outside the allowed paths, Orca kills the process and marks the task as failed.
Top comments (0)