Claude Code Integration

npm install -g @anthropic-ai/claude-code

brew install anthropic/tap/claude

export ANTHROPIC_API_KEY="sk-ant-..."

export OPENAI_API_KEY="sk-..."

export GEMINI_API_KEY="AI..."
# or
export GOOGLE_API_KEY="AI..."

# No API key needed - just ensure Ollama is running
export OLLAMA_BASE_URL="http://localhost:11434"

# Force a specific provider even if multiple keys are set
export ORCHEX_PROVIDER="openai"  # or: anthropic, gemini, ollama

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["@wundam/orchex", "mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["@wundam/orchex", "mcp"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["@wundam/orchex", "mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["@wundam/orchex", "mcp"],
      "env": {
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

{
  "mcpServers": {
    "orchex": {
      "command": "orchex",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

# Check Claude Code
claude --version

# Check Orchex
orchex --version

# Test MCP connection
claude "List available Orchex commands"

# LLM Provider (one required)
export ANTHROPIC_API_KEY="sk-ant-..."  # For Claude
export OPENAI_API_KEY="sk-..."         # For GPT-4/4.5
export GEMINI_API_KEY="AI..."          # For Gemini 1.5/2.0
export OLLAMA_BASE_URL="http://..."    # For local Ollama

# Provider Selection (optional - auto-detected if not set)
export ORCHEX_PROVIDER="openai"        # Force specific provider

# Optional
export ORCHEX_LOG_LEVEL="info"         # debug, info, warn, error
export ORCHEX_ARTIFACTS_DIR=".orchex"  # where to store outputs
export ORCHEX_MAX_PARALLEL=5           # max concurrent streams

{
  "mcpServers": {
    "orchex": {
      "command": "orchex",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "ORCHEX_PROVIDER": "openai",
        "ORCHEX_CLOUD_TOKEN": "${ORCHEX_CLOUD_TOKEN}",
        "ORCHEX_TEAM_ID": "team_abc123"
      },
      "settings": {
        "defaultExecutor": "cloud",
        "autoVerify": true,
        "saveArtifacts": true
      }
    }
  }
}

{
  "mcpServers": {
    "orchex-claude": {
      "command": "orchex",
      "args": ["mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    },
    "orchex-gpt": {
      "command": "orchex",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    },
    "orchex-local": {
      "command": "orchex",
      "args": ["mcp"],
      "env": {
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

claude
> /orchex-create "Add user authentication to the API"

claude
> /orchex-run manifest.yaml

# Dry run (show plan without executing)
> /orchex-run manifest.yaml --dry-run

# Run specific streams only
> /orchex-run manifest.yaml --streams="setup,core"

# Use cloud executor
> /orchex-run manifest.yaml --cloud

claude
> /orchex-status

claude
> /orchex-debug exec_abc123

claude
> /orchex-optimize manifest.yaml

# Start Claude Code
claude

# Create manifest
> Help me add a user profile page to my Next.js app.
> It should include:
> - Profile display with avatar
> - Edit form
> - API routes
> - Tests
> Can you create an Orchex manifest for this?

# Claude creates the manifest, then:
> /orchex-run profile-feature.yaml

# Monitor progress
> /orchex-status

# If any stream fails:
> /orchex-debug exec_abc123
> Apply the suggested fixes

claude "I have a bug where user sessions expire too quickly. 
The issue is in src/auth/session.ts. 
Can you create a manifest to:
1. Investigate the current timeout logic
2. Fix it to use 7 day expiration
3. Add tests
4. Update documentation"

# Claude creates manifest
> /orchex-run fix-session-bug.yaml

claude "I need to refactor src/utils/validation.ts to use Zod instead of custom validators.
Create a manifest that:
1. Analyzes current validation logic
2. Installs Zod
3. Rewrites validators
4. Updates all imports
5. Runs tests to verify
6. Updates type definitions"

> /orchex-run refactor-validation.yaml

claude "Generate API documentation for all routes in src/api/.
Include:
- OpenAPI spec
- Example requests/responses
- Authentication requirements
- Error codes

Create an Orchex manifest to do this systematically."

> /orchex-run generate-api-docs.yaml --streams="analyze,openapi,examples"

claude "Create a manifest to migrate from Express to Fastify:

Wave 1: Setup
- Install Fastify
- Create parallel server structure
- Set up plugins

Wave 2: Migrate routes
- Convert auth routes
- Convert API routes
- Convert webhooks

Wave 3: Testing
- Port tests
- Add integration tests
- Performance benchmarks

Wave 4: Cleanup
- Remove Express
- Update docs
- Update CI/CD"

> /orchex-run migrate-fastify.yaml

# In your project, create .claude/prompts/
mkdir -p .claude/prompts

# Create template
cat > .claude/prompts/add-feature.md << 'EOF'
Create an Orchex manifest for adding a new feature.

Feature: {{feature_name}}
Files affected: {{files}}

Include:
1. Implementation stream
2. Test stream (depends on implementation)
3. Documentation stream (depends on implementation)
4. Verification checks

Use parallel execution where possible.
EOF

# Use it
claude "@add-feature.md feature_name='dark mode' files='src/theme/'"

claude "Create a manifest that:
1. Creates a new branch 'feature/search'
2. Implements search functionality
3. Runs tests
4. Commits changes
5. Pushes to remote

Don't actually merge, just prepare the PR."

# .github/workflows/orchex-review.yml
name: Orchex Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code @wundam/orchex
      
      - name: Generate Review Manifest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude "Create an Orchex manifest to review this PR:
          - Check for test coverage
          - Verify documentation updates
          - Look for security issues
          - Suggest improvements
          Output: review-manifest.yaml"
      
      - name: Run Review
        run: orchex run review-manifest.yaml
      
      - name: Post Results
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const results = fs.readFileSync('.orchex/artifacts/review-results.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: results
            });

claude "Create a manifest with one stream that adds a new utility function"

claude "In my Next.js 14 app using TypeScript and Prisma,
create a manifest to add a blog post editor.
We use server components and app router."

# Claude generates manifest
> Show me the full manifest content before we run it

# Make adjustments
> In the 'api-routes' stream, also include rate limiting

# Then run
> /orchex-run blog-editor.yaml

> /orchex-run complex-migration.yaml --dry-run

# In one terminal
> /orchex-run large-refactor.yaml

# In another
watch -n 5 'orchex status'

mkdir -p .orchex/templates

# After successful execution
cp successful-feature.yaml .orchex/templates/add-feature-template.yaml

# Reuse later
claude "Use .orchex/templates/add-feature-template.yaml as a basis,
but adapt it for adding a comments feature instead."

# Check .mcp.json exists
cat .mcp.json

# Verify orchex is in PATH
which orchex

# Restart Claude Code session
exit
claude

# Explicitly connect
claude --mcp-config .mcp.json

# Validate manually
orchex validate manifest.yaml

# Show Claude the errors
claude "The manifest has these validation errors: [paste errors]
Please fix them."

# Check status with details
orchex status --verbose

# Cancel if needed
orchex cancel exec_abc123

# Debug
claude "The execution hung on stream 'database-migration'.
Here's the log: [paste log]
What went wrong?"

# Analyze context
claude "Review my manifest and suggest ways to reduce context size"

# Use optimize command
> /orchex-optimize expensive-manifest.yaml

# Limit context in manifest
# Edit to use more specific file patterns