Quick Start Guide

Get up and running with Orchex in 5 minutes. This guide assumes you've already installed Orchex and configured it as an MCP server.

What You'll Build

You'll create a simple workflow that:

Creates a new file
Writes content to it
Reads and validates the result

This demonstrates Orchex's core capabilities: orchestrating multiple steps, handling dependencies, and managing file operations.

Prerequisites

✅ Orchex installed (orchex --version works)
✅ ANTHROPIC_API_KEY environment variable set
✅ MCP server configured in Claude Desktop, Cursor, or Windsurf

Method 1: Using the CLI

Step 1: Create Your First Manifest

Create a new directory for your workflow:

mkdir my-first-workflow
cd my-first-workflow

Create a file called manifest.yaml:

tasks:
  - step: create-greeting
    prompt: |
      Create a file called 'greeting.txt' with a friendly welcome message.
      Make it warm and inviting for new Orchex users.
    provides:
      - greeting.txt

  - step: verify-greeting
    prompt: |
      Read the greeting.txt file and verify it contains a welcome message.
      Report what you find.
    needs:
      - greeting.txt

What's happening here?

step: A unique identifier for each task
prompt: Natural language instructions for Claude
provides: Files this step creates (outputs)
needs: Files this step requires (inputs)

Orchex automatically determines the execution order based on dependencies.

Step 2: Execute the Workflow

Run your workflow:

orchex execute manifest.yaml

You'll see:

Orchex analyzing the manifest
Steps executing in order
Real-time progress updates
Final results

Expected output:

🚀 Starting Orchex workflow execution...

📋 Workflow Plan:
  Wave 1: create-greeting
  Wave 2: verify-greeting

⚡ Executing wave 1...
  ✓ create-greeting completed

⚡ Executing wave 2...
  ✓ verify-greeting completed

✅ Workflow completed successfully!

Step 3: Verify the Results

Check that your file was created:

cat greeting.txt

You should see a friendly welcome message created by Claude!

Method 2: Using MCP in Claude Desktop/Cursor/Windsurf

Step 1: Start a Conversation

Open your AI assistant and start a new conversation. Try this prompt:

I want to create an Orchex workflow that:
1. Creates a file called "hello.txt" with a greeting
2. Reads the file and confirms it was created successfully

Can you execute this using the orchex_execute tool?

Step 2: Watch It Run

The assistant will:

Create a workflow manifest
Call the orchex_execute MCP tool
Show you the execution progress
Display the results

Step 3: Explore the Results

Ask follow-up questions:

"What files were created?"
"Can you show me the contents of hello.txt?"
"What steps did the workflow execute?"

Understanding the Output

Workflow Waves

Orchex organizes tasks into "waves" based on dependencies:

Wave 1: Tasks with no dependencies (can run in parallel)
Wave 2: Tasks that depend on Wave 1 outputs
Wave 3: Tasks that depend on Wave 2 outputs
...

Step Status

Each step shows its status:

⏳ Pending
⚡ Executing
✓ Completed
✗ Failed

Artifacts

Files created during execution are stored in:

CLI: Current directory or specified output directory
MCP: Temporary workspace (path shown in output)

Next Steps: More Complex Example

Now try something more practical. Create feature-workflow.yaml:

tasks:
  - step: plan-feature
    prompt: |
      Plan a new "dark mode" feature for a web application.
      Create a file called 'plan.md' with:
      - Feature requirements
      - Technical approach
      - Files that need to be modified
    provides:
      - plan.md

  - step: create-styles
    prompt: |
      Based on the plan in plan.md, create a CSS file called 'dark-mode.css'
      with dark mode styles including:
      - Background colors
      - Text colors
      - Transition effects
    needs:
      - plan.md
    provides:
      - dark-mode.css

  - step: create-toggle
    prompt: |
      Based on the plan in plan.md, create a JavaScript file called
      'theme-toggle.js' that toggles between light and dark mode.
    needs:
      - plan.md
    provides:
      - theme-toggle.js

  - step: create-readme
    prompt: |
      Create a README.md file that documents:
      - How to use the dark mode feature
      - Implementation details from the CSS and JS files
      - Installation instructions
    needs:
      - plan.md
      - dark-mode.css
      - theme-toggle.js
    provides:
      - README.md

Execute it:

orchex execute feature-workflow.yaml

What's different?

Multiple parallel tasks (Wave 2: create-styles and create-toggle run simultaneously)
Tasks with multiple dependencies (Wave 3: create-readme waits for three inputs)
Real-world feature development pattern

Common Patterns

Pattern 1: Sequential Pipeline

tasks:
  - step: fetch-data
    prompt: Create sample data in data.json
    provides: [data.json]

  - step: transform-data
    prompt: Transform data.json into processed.json
    needs: [data.json]
    provides: [processed.json]

  - step: generate-report
    prompt: Create report.md from processed.json
    needs: [processed.json]
    provides: [report.md]

Pattern 2: Parallel Processing

tasks:
  - step: process-users
    prompt: Extract user data from source.json
    needs: [source.json]
    provides: [users.json]

  - step: process-orders
    prompt: Extract order data from source.json
    needs: [source.json]
    provides: [orders.json]

  - step: merge-results
    prompt: Combine users.json and orders.json into final.json
    needs: [users.json, orders.json]
    provides: [final.json]

Pattern 3: Fan-out/Fan-in

tasks:
  - step: split-work
    prompt: Create three task files: task1.txt, task2.txt, task3.txt
    provides: [task1.txt, task2.txt, task3.txt]

  - step: process-task1
    prompt: Process task1.txt into result1.txt
    needs: [task1.txt]
    provides: [result1.txt]

  - step: process-task2
    prompt: Process task2.txt into result2.txt
    needs: [task2.txt]
    provides: [result2.txt]

  - step: process-task3
    prompt: Process task3.txt into result3.txt
    needs: [task3.txt]
    provides: [result3.txt]

  - step: combine-results
    prompt: Merge all results into final.txt
    needs: [result1.txt, result2.txt, result3.txt]
    provides: [final.txt]

Tips for Success

✅ Do

Be specific in prompts: "Create a CSS file with dark mode styles" is better than "make styles"
Declare all dependencies: List all files a step needs in needs
Use clear step names: create-user-model is better than step1
Start simple: Begin with 2-3 steps, then grow your workflow
Test incrementally: Validate each step works before adding more

❌ Don't

Create circular dependencies: Step A needs B, B needs A (Orchex will detect this)
Forget to declare outputs: If a step creates a file, list it in provides
Make prompts too vague: "Do something with data" won't give good results
Skip validation: Use orchex validate manifest.yaml before executing
Ignore errors: Read error messages—they guide you to fixes

Validation

Before executing, validate your manifest:

orchex validate manifest.yaml

This checks for:

✓ Valid YAML syntax
✓ Required fields present
✓ No circular dependencies
✓ All dependencies can be satisfied
✓ Proper step configuration

Troubleshooting Quick Fixes

"Circular dependency detected"

Problem: Step A depends on B, which depends on A.

Fix: Review your needs declarations. Draw a dependency graph to visualize the issue.

"Step failed to execute"

Problem: Claude couldn't complete the task.

Fix:

Make your prompt more specific
Check if required input files exist
Verify file permissions
Review the error message for hints

"File not found"

Problem: A step expects a file that doesn't exist.

Fix:

Ensure the file is listed in a previous step's provides
Check spelling in needs and provides
Verify the step creating the file completed successfully

"Invalid manifest format"

Problem: YAML syntax error or missing required fields.

Fix:

Run orchex validate manifest.yaml for details
Check indentation (YAML is whitespace-sensitive)
Ensure all required fields are present

What You've Learned

✅ How to create an Orchex manifest with tasks and dependencies

✅ How to execute workflows via CLI and MCP

✅ How Orchex organizes tasks into parallel waves

✅ Common workflow patterns (sequential, parallel, fan-out/fan-in)

✅ Best practices for writing effective prompts

✅ How to validate and troubleshoot workflows

Next Steps

Explore Examples

Check out real-world examples in the examples/ directory:

# Hello World - simplest possible workflow
cd examples/hello-world
orchex execute manifest.yaml

# Add Feature - realistic feature development
cd examples/add-feature
orchex execute manifest.yaml

# Fix Bug - debugging and patching workflow
cd examples/fix-bug
orchex execute manifest.yaml

Learn Advanced Features

Concepts: Deep dive into Orchex architecture
Wave Planning: Optimize parallel execution
Error Handling: Robust workflow design
Cloud Execution: Run workflows in the cloud

Try Real Projects

Use Orchex for actual work:

Code refactoring: Break large refactors into orchestrated steps
Documentation: Generate docs from code across multiple files
Data processing: ETL pipelines with validation and transformation
Testing: Orchestrate test generation, execution, and reporting
Infrastructure: Coordinate configuration and deployment tasks

Join the Community

Share your workflows: Post examples and patterns you discover
Ask questions: Get help from experienced Orchex users
Contribute: Improve docs, add features, report bugs

Quick Reference

Basic Manifest Structure

tasks:
  - step: unique-step-name
    prompt: |
      Natural language instructions for Claude.
      Be specific about what to create or do.
    needs:              # Optional: input files
      - input-file.txt
    provides:           # Optional: output files
      - output-file.txt

Common Commands

# Execute a workflow
orchex execute manifest.yaml

# Validate a manifest
orchex validate manifest.yaml

# View help
orchex --help

# Check version
orchex --version

# Enable debug logging
DEBUG=orchex:* orchex execute manifest.yaml

MCP Tools

When using Orchex through MCP:

orchex_execute - Execute a workflow from manifest
orchex_plan - Plan workflow waves without executing
orchex_validate - Validate manifest structure
orchex_status - Check execution status

Getting Help

Stuck? Here's where to get help:

Check the examples: Most common patterns are demonstrated
Read the error message: Orchex provides detailed, actionable errors
Validate your manifest: orchex validate catches many issues
Enable debug logging: DEBUG=orchex:* shows what's happening
Review the docs: Dive deeper into Concepts
Ask the community: GitHub Issues, Discord, or forums

Ready to build something amazing? Start with a simple workflow, iterate, and grow it into complex orchestrations. Orchex scales with your needs.

Happy orchestrating! 🚀