Quick Start

Get orchex running in 5 minutes. By the end of this guide, you'll have executed your first parallel orchestration.

Prerequisites

  • Node.js 18+ — Download
  • One LLM API key — any of:
    • OpenAI (OPENAI_API_KEY)
    • Anthropic (ANTHROPIC_API_KEY)
    • Google Gemini (GOOGLE_API_KEY)
    • DeepSeek (DEEPSEEK_API_KEY)
    • Ollama (no key needed — local models)

Step 1: Install

No installation required — use npx:

npx @wundam/orchex

Or install globally:

npm install -g @wundam/orchex

Step 2: Configure Your MCP Client

orchex works as an MCP (Model Context Protocol) server inside your AI coding assistant. Add it to your client's configuration:

Claude Code

Add to .mcp.json in your project root:

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

Cursor

Add to your Cursor MCP settings (Settings > MCP Servers):

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

Windsurf

Add to your Windsurf MCP configuration:

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

Step 3: Set Your API Key

Export your LLM API key as an environment variable:

# Pick one:
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AI..."
export DEEPSEEK_API_KEY="sk-..."

Or add it to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Step 4: Run Your First Orchestration

Ask your AI assistant to run an orchex orchestration. It will use the MCP tools automatically:

You: "Use orchex to add a hello-world feature with two parallel streams"

Behind the scenes, the assistant calls the orchex MCP tools:

// 1. Initialize the orchestration
orchex.init({
  feature: "hello-world",
  streams: {
    "greeting": {
      name: "Greeting Module",
      owns: ["src/greeting.ts"],
      plan: "Create a greeting module that exports a greet(name) function"
    },
    "greeting-test": {
      name: "Greeting Tests",
      owns: ["tests/greeting.test.ts"],
      reads: ["src/greeting.ts"],
      deps: ["greeting"],
      plan: "Write tests for the greet function",
      verify: ["npx vitest run tests/greeting.test.ts"]
    }
  }
});

// 2. Execute all waves
orchex.execute({ mode: "auto" });

Step 5: What Happened?

orchex resolved the dependency graph and executed in 2 waves:

Wave 1: [greeting]        — Created src/greeting.ts
Wave 2: [greeting-test]   — Created tests/greeting.test.ts, ran tests

Key concepts demonstrated:

  • Streams — greeting and greeting-test are independent units of work
  • Ownership — Each stream owns specific files. greeting-test cannot modify src/greeting.ts
  • Dependencies — greeting-test depends on greeting, so it runs in Wave 2
  • Verification — The test stream ran vitest automatically to verify its work

Next Steps