Core Concepts

orchex orchestrates parallel AI agents with safety guarantees. Understanding these five concepts unlocks its full power.

Streams

A stream is the fundamental unit of work in orchex. Each stream is an independent task assigned to one LLM agent.

Stream Properties

Example

{
  "auth-middleware": {
    name: "Auth Middleware",
    owns: ["src/middleware/auth.ts"],
    reads: ["src/types/user.ts"],
    plan: "Create Express middleware that validates JWT tokens from the Authorization header",
    verify: ["npx tsc --noEmit"]
  }
}

The agent executing this stream can only write to src/middleware/auth.ts. It can read src/types/user.ts for type information but cannot modify it.

Waves

Waves are groups of streams that execute in parallel. orchex automatically computes waves from the dependency graph using topological sort.

How Waves Work

1. Wave 1: All streams with no dependencies run simultaneously
2. Wave 2: Streams whose dependencies all completed in Wave 1
3. Wave N: Streams whose dependencies all completed in previous waves

Example

Streams:
  A (no deps)     ─┐
  B (no deps)     ─┤── Wave 1 (parallel)
  C (no deps)     ─┘
  D (deps: [A])   ─┐
  E (deps: [B,C]) ─┘── Wave 2 (parallel)
  F (deps: [D,E]) ──── Wave 3

orchex executes A, B, and C simultaneously. When all three finish, D and E run in parallel. Finally, F runs alone.

Why Waves Matter

• Speed: 6 streams in 3 waves instead of 6 sequential steps
• Safety: Each wave only starts after previous waves verify successfully
• Rate limits: Parallel execution across multiple LLM providers bypasses per-provider rate limits

Ownership

Ownership is orchex's core safety mechanism. Every stream declares which files it owns (can write) and which it reads (can only read).

Rules

1. Exclusive writes: Only one stream can own a given file at any time
2. Shared reads: Multiple streams can read the same file
3. Enforcement: If an agent tries to write a file it doesn't own, the write is blocked
4. Verification: After each stream completes, ownership violations are checked before proceeding

Why Ownership Exists

Without ownership, parallel agents would overwrite each other's work. Consider:

Stream A: Writes src/config.ts with database settings
Stream B: Writes src/config.ts with auth settings  (runs in parallel)

Without ownership, the last stream to finish wins — and the other's work is lost. With ownership, this configuration is rejected at init time: two streams cannot own the same file.

owns vs reads

{
  "api-routes": {
    owns: ["src/routes/api.ts"],       // Can create/modify
    reads: ["src/types/api.ts"],       // Can only read
    deps: ["api-types"]                // Wait for types first
  },
  "api-types": {
    owns: ["src/types/api.ts"],        // Types stream owns this file
  }
}

Self-Healing

When a stream fails, orchex doesn't just retry blindly. It categorizes the error and generates a targeted fix stream with specific repair instructions.

Error Categories

orchex recognizes 10 distinct error types:

Fix Chain

When a stream fails:

1. orchex categorizes the error
2. A fix stream is generated with the error details and original plan
3. The fix stream inherits the parent's file ownership
4. If the fix fails, another fix stream is generated (up to 3 attempts)
5. After 3 failed attempts, the stream is marked as failed and reported

When to Intervene

Self-healing handles most issues automatically. You should intervene when:

• The same error repeats across all 3 fix attempts
• The error is architectural (wrong approach, not just wrong code)
• A dependency is missing from the stream definition

Providers

orchex supports 5 LLM providers. You bring your own API keys (BYOK) — orchex never stores or proxies your keys locally.

Supported Providers

Provider Selection

Each stream can target a specific provider/model, or orchex auto-selects based on availability:

{
  "complex-task": {
    name: "Complex Refactor",
    plan: "...",
    // Provider auto-selected from available keys
  }
}

Rate Limit Strategy

By setting up multiple provider API keys, orchex distributes work across providers. If one provider rate-limits, other streams continue on different providers — no waiting.