@wundam/orchex

orchex

Describe what you want. Orchex plans, parallelizes, and executes — safely.

The orchestration engine inside your AI coding assistant. Describe your intent, orchex auto-generates a plan, splits it into parallel streams with file ownership enforcement, self-healing failures, and multi-LLM routing. Your AI assistant is the driver. Orchex is the engine.

Why Orchex

Your AI assistant does tasks one at a time. Orchex makes it do 10 at once — safely.

• Parallel Execution — Multiple streams run simultaneously in dependency-aware waves. 5-10x faster than serial prompting.
• Ownership Enforcement — Each stream can only modify files in its owns array. No two agents touch the same file. Zero conflicts.
• orchex run — Describe what you want, get parallel execution. Auto-generates plans, previews waves, executes with ownership enforcement.
• orchex learn — The advanced path. Paste a markdown plan, get executable parallel streams with dependency inference and anti-pattern detection.
• Self-Healing — Categorized error analysis with targeted fix streams. Not blind retry. Model validation before execution prevents wasted API calls.
• Multi-LLM — OpenAI, Gemini, Claude, DeepSeek, Kimi (Moonshot AI), Ollama, AWS Bedrock. Dynamic model registry auto-discovers available models. Key-aware routing prevents "model not found" errors.
• BYOK — Bring your own API key from any supported provider. You control costs.

Prerequisites

• Node.js >= 18
• LLM API key — set via environment variable or store on the dashboard and sync with orchex login:
  • ANTHROPIC_API_KEY for Anthropic Claude
  • OPENAI_API_KEY for OpenAI (GPT-4.1, o1, o3)
  • GEMINI_API_KEY for Google Gemini
  • DEEPSEEK_API_KEY for DeepSeek (V3, Coder, R1)
  • KIMI_API_KEY for Kimi / Moonshot AI (K2, moonshot-v1; MOONSHOT_API_KEY alias accepted)
  • Configure Ollama for local models
  • AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY for AWS Bedrock

Install

npm install -g @wundam/orchex

Or use directly:

npx @wundam/orchex

Cloud Setup (Optional)

Connect to orchex cloud for managed execution:

orchex login

Your browser opens — log in or create a free account, click Allow. Token saved automatically. API keys stored on the dashboard are synced to your local machine so orchex run works without environment variables.

orchex status          # Check tier and trial runs
orchex logout          # Clear credentials and cached keys
orchex --help          # All commands

See the cloud setup guide for full details.

MCP Configuration

Auto-configure for your IDE (Cursor, Windsurf, Claude Code):

npx @wundam/orchex setup

Or manually add to your MCP config (e.g. project .mcp.json):

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}

Zero-Config LLM Discovery

Once connected, your AI assistant automatically receives:

• Instructions — Core concepts, all 12 tools, provider setup, and tier info. No prompt engineering needed.
• 8 on-demand resources via orchex:// URIs — deep guides on streams, waves, ownership, self-healing, providers, examples, and API reference. The LLM reads these when it needs them.
• IDE auto-detection — orchex setup detects Cursor, Windsurf, and other MCP clients, writes the correct config, and merges with existing MCP servers.

Your AI assistant knows how to use Orchex the moment it connects.

Usage

1. Initialize an orchestration

orchex.init({
  feature: "user-authentication",
  streams: {
    types: {
      name: "Define types",
      deps: [],
      owns: ["src/types.ts"],
      reads: ["src/config.ts"],
      plan: "Define TypeScript interfaces for auth",
      setup: ["npm install"],
      verify: ["npm test"]
    },
    api: {
      name: "Build API",
      deps: ["types"],
      owns: ["src/api.ts"],
      reads: ["src/types.ts"]
    },
    tests: {
      name: "Write tests",
      deps: ["types", "api"],
      owns: ["tests/"],
      verify: ["npm test"]
    }
  }
})

2. Execute

orchex.execute({ mode: "auto" })

Calculates waves from dependencies (topological sort), then executes each wave in parallel — running setup commands, calling the LLM API, applying file operations with ownership enforcement, and running verification commands.

Wave plan for the example above:

• Wave 1: types (no deps)
• Wave 2: api (depends on types)
• Wave 3: tests (depends on types + api)

Modes:

• wave (default) — execute one wave and return. Call repeatedly to step through.
• auto — execute all waves sequentially until done.
• dry_run: true — generate prompts without calling the LLM API.

3. Check status

orchex.status()

4. Complete

orchex.complete({ archive: true })

CLI Commands

orchex run "Add user auth"          # Auto-plan and execute from intent
orchex run "..." --yes              # Skip approval prompt
orchex run "..." --dry-run          # Generate plan only, don't execute
orchex run "..." --provider openai  # Use specific provider
orchex setup                        # Auto-detect IDE and configure MCP
orchex setup --ide cursor           # Target a specific IDE
orchex login                        # Authenticate with orchex cloud
orchex logout                       # Log out of cloud
orchex status                       # Show login state, tier, trial runs
orchex config                       # Show/set configuration
orchex reset-learning               # Clear learning data

MCP Tools

Tool	Description
init	Initialize orchestration with feature name and streams
add_stream	Add a stream to the active orchestration
status	Get orchestration progress and wave info
execute	Run the orchestration — calls LLM API, applies artifacts, verifies
complete	Mark streams done or archive orchestration
recover	Reset stuck/failed streams for retry or skip
learn	Parse a markdown plan into stream definitions
init-plan	Generate an annotated plan template
auto	One-shot: intent → plan → preview → execute → report
reset-learning	Clear learning data (thresholds, patterns, reports)
rollback-stream	Revert a stream's file changes via git
reload	Restart MCP server to pick up code changes

Stream Definition

Field	Type	Description
name	string	Human-readable stream name
deps	string[]	Stream IDs this depends on (determines wave order)
owns	string[]	Files this stream can create/modify (ownership enforcement)
reads	string[]	Files this stream needs to read (included in context, not writable)
plan	string	Implementation instructions for the agent
setup	string[]	Shell commands to run before execution
verify	string[]	Shell commands to run after execution
timeoutMs	number	Per-stream timeout override in milliseconds (optional)

Stream Slicing Best Practices

One stream = one atomic deliverable. If your stream description uses "and" between distinct concepts, split it.

Slicing heuristics:

• owns > 4 distinct files → Split
• reads > 4 files → Split (high synthesis complexity)
• Expected output > 6,000 tokens → Split
• Code implementation + its tests → Keep together
• Tutorials → Section into intro/walkthrough/conclusion streams

Development

npm install
npm run build    # TypeScript compilation
npm test         # Run tests
npm run dev      # Run with tsx (development)

For local development, point .mcp.json to your local build:

{
  "mcpServers": {
    "orchex": {
      "command": "node",
      "args": ["./bin/orchex.js"],
      "cwd": "/path/to/orchex"
    }
  }
}

Pricing

Free local tier included — no account required. Cloud tiers unlock more streams, waves, providers, and run history.

Founding Members — 50 slots at $49/year with Pro-level limits (200 runs, 30 agents, 20 waves, unlimited providers). Locked-in pricing for life. Claim a slot while they last.

See orchex.dev/pricing for all plans and limits.

License

BSL 1.1 — free to use for any purpose except hosting as a competing commercial orchestration service. Converts to Apache 2.0 on 2030-01-29.