🔌 Orchestro Integration Guide

Complete guide to integrate Orchestro MCP server into your existing Claude Code projects

This guide shows you how to add Orchestro's AI orchestration capabilities to any existing development project, enabling intelligent task management, dependency tracking, and pattern learning.

✅ Prerequisites

Before integrating Orchestro, ensure you have:

✅ Node.js 18+ installed
✅ Claude Code installed and working
✅ Supabase account (free tier works perfectly)
✅ Existing project you want to orchestrate

# Check Node.js version
node --version  # Should be 18.0.0 or higher

# Verify Claude Code is installed
# It should be in /Applications/Claude.app (macOS)

📥 Installation

Step 1: Clone Orchestro

# Navigate to your development folder
cd ~/Documents

# Clone Orchestro
git clone https://github.com/yourusername/orchestro.git
cd orchestro

# Install dependencies
npm install

# Build TypeScript
npm run build

Expected output:

✓ TypeScript compilation successful
✓ MCP server built to dist/server.js

Step 2: Setup Supabase Database

Option A: Use Our Schema (Recommended)

# 1. Create Supabase project at https://supabase.com
# 2. Copy connection string from Project Settings > Database

# 3. Run migrations
export DATABASE_URL="your-supabase-connection-string"
npm run migrate

Option B: Manual Setup

-- Run these SQL scripts in Supabase SQL Editor
-- In order:
1. src/db/migrations/001_initial_schema.sql
2. src/db/migrations/002_add_dependency_completion_check.sql
3. src/db/migrations/003_add_tasks_metadata.sql
4. src/db/migrations/004_event_queue.sql
5. src/db/migrations/005_code_entities.sql
6. src/db/migrations/006_fix_status_transition_trigger.sql
7. src/db/migrations/007_add_user_story_grouping.sql
8. src/db/migrations/008_add_task_metadata_fields.sql
9. src/db/migrations/009_add_pattern_frequency_tracking.sql

Step 3: Configure Environment

# Create .env file in orchestro root
cat > .env << EOF
# Supabase Configuration
DATABASE_URL=postgresql://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
SUPABASE_URL=https://[PROJECT-REF].supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key

# Optional: Project Settings
PROJECT_NAME=My Project
PROJECT_ID=auto-generated-uuid
EOF

🔐 Security Note: Never commit .env file to git!

⚙️ Configuration

Step 1: Configure Claude Code

macOS

# Open Claude Code config
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

# Open in notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

Linux

# Open in editor
nano ~/.config/Claude/claude_desktop_config.json

Step 2: Add Orchestro MCP Server

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "orchestro": {
      "command": "node",
      "args": ["/absolute/path/to/orchestro/dist/server.js"],
      "env": {
        "DATABASE_URL": "your-supabase-connection-string"
      }
    }
  }
}

⚠️ Important:

Use absolute paths (not ~ or ./)
Replace /absolute/path/to/orchestro with your actual path
Example: /Users/john/Documents/orchestro/dist/server.js

Step 3: Verify Configuration

// ✅ Good example
{
  "mcpServers": {
    "orchestro": {
      "command": "node",
      "args": ["/Users/john/Documents/orchestro/dist/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://postgres.abc123:pass@aws-0-eu-central-1.pooler.supabase.com:6543/postgres"
      }
    }
  }
}

// ❌ Bad example (relative paths don't work!)
{
  "mcpServers": {
    "orchestro": {
      "command": "node",
      "args": ["./orchestro/dist/server.js"],  // ❌ Don't use relative paths
      "env": {
        "DATABASE_URL": "..."
      }
    }
  }
}

Step 4: Restart Claude Code

# macOS: Quit and reopen
# Or use Activity Monitor to force quit

# Windows: Close and reopen
# Or use Task Manager to end process

# Linux:
killall claude-code
claude-code &

🎯 Project Setup

Create Project in Orchestro

Option 1: Via Dashboard

# Start dashboard
cd orchestro/web-dashboard
npm install
npm run dev

# Open http://localhost:3000
# Click "Create Project"
# Fill in:
#   - Name: Your Project Name
#   - Status: active
#   - Description: What you're building

Option 2: Via Claude Code

In Claude Code, ask:

Please create a new Orchestro project with:
- Name: "My E-commerce Platform"
- Status: active
- Description: "Building an e-commerce platform with Next.js and Stripe"

Claude will use the get_project_info tool to create your project.

Link to Existing Codebase

Orchestro needs to know about your existing project structure:

# In Claude Code, run:
"Analyze my current codebase at /path/to/your/project and
create initial resource nodes in Orchestro"

This will:

Scan your project structure
Create resource nodes (files, components, APIs)
Build initial dependency graph

🔗 Connecting to Existing Projects

Scenario 1: Existing Next.js Project

Your project structure:

my-nextjs-app/
├── app/
├── components/
├── lib/
└── package.json

Integration steps:

Open Claude Code in your project directory

cd /path/to/my-nextjs-app
code .  # Or open with Claude Code

Verify Orchestro connection

In Claude Code: "Show me all orchestro tools"

Expected: List of 27 MCP tools

Create first user story

"Create a user story in Orchestro:
'User should be able to filter products by category'"

Decompose with AI

"Decompose this story into technical tasks using orchestro"

Start implementation

"Prepare the first task for execution and analyze
which files in my Next.js app need to be modified"

Scenario 2: Backend API Project

Your project structure:

my-api/
├── src/
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   └── services/
└── package.json

Integration steps:

Initialize Orchestro project

"Create an Orchestro project for my Express API
located at /Users/john/projects/my-api"

Import existing tasks from TODO.md (if you have one)

"Read my TODO.md file and create Orchestro tasks from it"

Build dependency graph

"Analyze my API codebase and build a resource dependency
graph in Orchestro, focusing on:
- Controllers and their routes
- Models and database tables
- Service layer dependencies"

Start orchestrated development

"List all Orchestro tasks for this project and
prepare the first one for execution"

Scenario 3: Monorepo with Multiple Apps

Your project structure:

monorepo/
├── apps/
│   ├── web/          # Next.js frontend
│   ├── mobile/       # React Native
│   └── api/          # Express backend
├── packages/
│   └── shared/       # Shared utilities
└── package.json

Integration approach:

Create separate Orchestro projects (or use tags)

"Create 3 Orchestro projects:
1. 'Monorepo - Web App'
2. 'Monorepo - Mobile App'
3. 'Monorepo - API'

Tag all with: ['monorepo', 'my-company']"

Track cross-project dependencies

"When I create tasks that modify the 'shared' package,
automatically flag potential conflicts across all 3 projects"

Unified dashboard view

Open http://localhost:3000
Filter tasks by tag: 'monorepo'
See all projects together

🚀 First Steps

1. Verify Installation

# In Claude Code, ask:
"Test Orchestro integration by:
1. Getting project info
2. Creating a test task
3. Listing all tasks"

Expected output:

✅ Project info retrieved
✅ Test task created with ID: abc-123
✅ 1 task listed successfully

2. Create Your First User Story

"Create an Orchestro user story:
Title: 'User authentication with email/password'
Description: 'Users should be able to sign up, login,
and reset password using email and password'"

3. Decompose into Tasks

"Decompose this user story using Orchestro AI decomposition"

Result: 7-10 technical tasks with dependencies automatically created!

4. Implement First Task

"Prepare the first task for execution and show me:
- Which files to modify
- What dependencies exist
- Any potential risks"

5. Track Progress on Dashboard

# Open dashboard
open http://localhost:3000

# You'll see:
- Kanban board with your tasks
- Dependency graph visualization
- Real-time progress updates

🔄 Workflow Integration

Daily Development Workflow

Morning: Plan

# 1. Open dashboard
open http://localhost:3000

# 2. In Claude Code:
"Show me today's Orchestro tasks assigned to me,
ordered by priority"

# 3. Review dependencies
"Show dependency graph for task [task-id]"

During: Implement

# 1. Prepare task
"Prepare task [task-id] for execution"

# 2. Analyze codebase (Claude uses Read/Grep/Glob)
# Orchestro provides structured prompt

# 3. Save analysis
"Save my analysis results to Orchestro"

# 4. Get enriched context
"Get execution prompt for task [task-id]"
# Includes: past patterns, risks, guidelines

# 5. Implement with confidence
# Claude has full context now!

# 6. Record learning
"Add feedback to Orchestro:
- Pattern: 'JWT authentication implementation'
- Type: success
- Feedback: 'Used bcrypt for hashing, works perfectly'"

Evening: Review

# 1. Update task statuses
"Update all my in-progress tasks to done in Orchestro"

# 2. Check for conflicts
"Check if any of my tasks conflict with other ongoing work"

# 3. Review pattern learnings
"Show me today's pattern learnings in Orchestro"

# 4. Export report (for PM/stakeholders)
"Export today's progress from Orchestro as markdown"

Team Workflow

Product Manager Flow

# 1. Write user stories in dashboard
http://localhost:3000 > Click "New Story"

# 2. AI decomposition
Click "Decompose with AI" on story

# 3. Review technical tasks
Tasks appear automatically with:
- Time estimates
- Dependencies
- Complexity levels

# 4. Assign to developers
Drag tasks to "To Do" column
Set assignee via dropdown

# 5. Monitor progress
Real-time Kanban updates
Risk indicators show up automatically

Developer Flow

# 1. Pick task from Kanban
http://localhost:3000 > Drag task to "In Progress"

# 2. In Claude Code:
"Prepare my current in-progress Orchestro task"

# 3. Implement with AI assistance
Full context provided automatically

# 4. Record decisions
"Record this decision in Orchestro:
Why: Chose Redis over Memcached
Alternatives: Memcached, in-memory cache
Trade-offs: Redis has persistence, slightly slower"

# 5. Complete task
"Mark task as done and add success feedback"

🐛 Troubleshooting

Issue 1: MCP Server Not Connecting

Symptoms:

"I don't see orchestro tools in Claude Code"

Solutions:

Check config path is absolute

# ❌ Wrong
"args": ["./orchestro/dist/server.js"]

# ✅ Correct
"args": ["/Users/john/Documents/orchestro/dist/server.js"]

Verify build completed

cd /path/to/orchestro
npm run build
# Check dist/server.js exists
ls -la dist/server.js

Test server manually

cd /path/to/orchestro
DATABASE_URL="your-url" node dist/server.js
# Should output: "MCP server running on stdio"

Check Claude Code logs

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Look for Orchestro connection errors

Issue 2: Database Connection Fails

Symptoms:

Error: connect ECONNREFUSED
or
Error: password authentication failed

Solutions:

Verify connection string

# Test with psql
psql "$DATABASE_URL" -c "SELECT 1"
# Should return: 1

Check Supabase pooler URL (not direct connection)

# ✅ Correct (pooler)
postgresql://postgres.abc:pass@aws-0-region.pooler.supabase.com:6543/postgres

# ❌ Wrong (direct)
postgresql://postgres.abc:pass@db.abc.supabase.co:5432/postgres

Verify firewall allows connection

# Test connection
nc -zv aws-0-region.pooler.supabase.com 6543
# Should output: Connection succeeded

Issue 3: Dashboard Not Showing Tasks

Symptoms:

Dashboard shows empty Kanban board

Solutions:

Check WebSocket connection

# Open browser console on http://localhost:3000
# Look for: "Socket connected" message

Verify tasks exist in database

-- Run in Supabase SQL Editor
SELECT * FROM tasks;

Check API routes

# Test API directly
curl http://localhost:3000/api/tasks
# Should return JSON array

Restart dashboard

cd orchestro/web-dashboard
rm -rf .next
npm run dev

Issue 4: AI Decomposition Fails

Symptoms:

"Error decomposing user story"

Solutions:

Check API key configuration (if using external AI)
```
# In .env
OPENAI_API_KEY=sk-...
```

Verify user story format

# ✅ Good format
"User should be able to login with email/password"

# ❌ Too vague
"Login feature"

Check logs

# In orchestro root
tail -f logs/decompose.log

Issue 5: Pattern Learning Not Working

Symptoms:

detect_failure_patterns returns empty array

Solutions:

Ensure minimum data exists

-- Check learnings table
SELECT pattern, type, COUNT(*)
FROM learnings
WHERE pattern IS NOT NULL
GROUP BY pattern, type;

-- Need at least 3 occurrences per pattern

Verify trigger is active

-- Check trigger exists
SELECT * FROM information_schema.triggers
WHERE trigger_name = 'track_pattern_frequency';

Manually test pattern tracking

In Claude Code:
"Add this feedback to Orchestro:
- Pattern: 'test pattern'
- Type: failure
- Feedback: 'test'

Then check pattern_frequency table"

🎓 Best Practices

1. Project Organization

✅ Do:

Create one Orchestro project per codebase
Use tags to group related tasks
Set clear assignees and priorities
Write detailed user stories

❌ Don't:

Mix unrelated projects in one Orchestro instance
Leave tasks without descriptions
Skip dependency mapping

2. Task Management

✅ Do:

Decompose user stories with AI
Review auto-generated dependencies
Record decisions with rationale
Add feedback after completing tasks

❌ Don't:

Create tasks manually when AI can help
Ignore risk warnings
Skip pattern learning (add_feedback)

3. Team Collaboration

✅ Do:

Keep dashboard visible to team
Export reports for stakeholders
Review conflicts before merging
Share successful patterns

❌ Don't:

Work on same files without coordination
Hide risks from product team
Ignore dependency warnings

🔗 Next Steps

Now that Orchestro is integrated:

📖 Read: PM_GUIDE.md - For product managers
💻 Read: DEV_GUIDE.md - For developers
🎯 Try: EXAMPLES.md - Real-world examples
🏗️ Understand: ARCHITECTURE.md - How it works

💬 Get Help

📧 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
🌐 Dashboard: http://localhost:3000
📖 Docs: Full documentation

🎭 Happy Orchestrating!

Your development workflow is about to get a whole lot smarter.

← Back to README

FilesExpand file tree

INTEGRATION_GUIDE.md

Latest commit

History

INTEGRATION_GUIDE.md

File metadata and controls

🔌 Orchestro Integration Guide

📋 Table of Contents

✅ Prerequisites

📥 Installation

Step 1: Clone Orchestro

Step 2: Setup Supabase Database

Option A: Use Our Schema (Recommended)

Option B: Manual Setup

Step 3: Configure Environment

⚙️ Configuration

Step 1: Configure Claude Code

macOS

Windows

Linux

Step 2: Add Orchestro MCP Server

Step 3: Verify Configuration

Step 4: Restart Claude Code

🎯 Project Setup

Create Project in Orchestro

Option 1: Via Dashboard

Option 2: Via Claude Code

Link to Existing Codebase

🔗 Connecting to Existing Projects

Scenario 1: Existing Next.js Project

Scenario 2: Backend API Project

Scenario 3: Monorepo with Multiple Apps

🚀 First Steps

1. Verify Installation

2. Create Your First User Story

3. Decompose into Tasks

4. Implement First Task

5. Track Progress on Dashboard

🔄 Workflow Integration

Daily Development Workflow

Morning: Plan

During: Implement

Evening: Review

Team Workflow

Product Manager Flow

Developer Flow

🐛 Troubleshooting

Issue 1: MCP Server Not Connecting

Issue 2: Database Connection Fails

Issue 3: Dashboard Not Showing Tasks

Issue 4: AI Decomposition Fails

Issue 5: Pattern Learning Not Working

🎓 Best Practices

1. Project Organization

2. Task Management

3. Team Collaboration

🔗 Next Steps

💬 Get Help