project-orchestrator

name	project-orchestrator
description	AI agent orchestrator with Neo4j knowledge graph, Meilisearch search, and Tree-sitter parsing. Use for coordinating multiple coding agents on complex projects with shared context and plans.
metadata	{"clawdbot":{"emoji":"🎯","requires":{"bins":["docker","cargo"]}}}

Project Orchestrator

Coordinate multiple AI coding agents with a shared knowledge base.

Features

• Multi-Project Support: Manage multiple codebases with isolated data
• Neo4j Knowledge Graph: Code structure, relationships, plans, decisions
• Meilisearch: Fast semantic search across code and decisions
• Tree-sitter: Precise code parsing for 16 languages
• Plan Management: Structured tasks with dependencies and constraints
• MCP Integration: 22 mega-tools for Claude Code, OpenAI Agents, and Cursor
• Authentication: Google OAuth2, OIDC, and Password login + JWT with deny-by-default security
• Chat WebSocket: Real-time conversational AI via Claude integration
• Event System: CRUD event notifications via WebSocket
• NATS Integration: Inter-process event sync for multi-instance deployments
• YAML Configuration: Hierarchical config with env var overrides

Documentation

• Installation Guide
• Getting Started Tutorial
• API Reference
• MCP Tools Reference
• Integration Guides: Claude Code | OpenAI | Cursor

Quick Start

1. Start the backends

cd {baseDir}
docker compose up -d

2. Build and run the orchestrator

cargo build --release
./target/release/orchestrator serve

Or with Docker:

docker compose up -d

3. Sync your codebase

# Via CLI
./target/release/orch sync --path /path/to/project

# Via API
curl -X POST http://localhost:8080/api/sync \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/project"}'

Usage

Create a project

# Create a new project
curl -X POST http://localhost:8080/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Embryon",
    "root_path": "/Users/triviere/projects/embryon",
    "description": "Neural network composition framework"
  }'

# List all projects
curl http://localhost:8080/api/projects

# Sync a project
curl -X POST http://localhost:8080/api/projects/embryon/sync

# Search code within a project
curl "http://localhost:8080/api/projects/embryon/code/search?q=tensor&limit=10"

Create a plan

orch plan create \
  --title "Implement GPU Backend" \
  --desc "Add Metal GPU support for neural network operations" \
  --priority 10

Add tasks to the plan

orch task add \
  --plan <plan-id> \
  --desc "Implement MatMul Metal shader"

orch task add \
  --plan <plan-id> \
  --desc "Add attention layer GPU support" \
  --depends <task-1-id>

Get context for an agent

# JSON context
orch context --plan <plan-id> --task <task-id>

# Ready-to-use prompt
orch context --plan <plan-id> --task <task-id> --prompt

Record decisions

orch decision add \
  --task <task-id> \
  --desc "Use shared memory for tile-based MatMul" \
  --rationale "Better cache locality, 2x performance improvement"

Search past decisions

orch decision search "memory management GPU"

API Endpoints

Projects (Multi-Project Support)

Method	Path	Description
GET	/api/projects	List all projects
POST	/api/projects	Create a new project
GET	/api/projects/{slug}	Get project by slug
DELETE	/api/projects/{slug}	Delete a project
POST	/api/projects/{slug}/sync	Sync project's codebase
GET	/api/projects/{slug}/plans	List project's plans
GET	/api/projects/{slug}/code/search	Search code in project

Plans & Tasks

Method	Path	Description
GET	/health	Health check
GET	/api/plans	List active plans
POST	/api/plans	Create plan
GET	/api/plans/{id}	Get plan details
PATCH	/api/plans/{id}	Update plan status
GET	/api/plans/{id}/next-task	Get next available task
POST	/api/plans/{id}/tasks	Add task to plan
GET	/api/tasks/{id}	Get task details
PATCH	/api/tasks/{id}	Update task
GET	/api/plans/{plan}/tasks/{task}/context	Get task context
GET	/api/plans/{plan}/tasks/{task}/prompt	Get generated prompt
POST	/api/tasks/{id}/decisions	Add decision
GET	/api/decisions/search?q=...	Search decisions

Sync & Watch

Method	Path	Description
POST	/api/sync	Sync directory to knowledge base
GET	/api/watch	Get file watcher status
POST	/api/watch	Start watching a directory
DELETE	/api/watch	Stop file watcher
POST	/api/wake	Agent completion webhook

Code Exploration (Graph + Search)

Method	Path	Description
GET	/api/code/search?q=...	Semantic code search
GET	/api/code/symbols/{path}	Get symbols in a file
GET	/api/code/references?symbol=...	Find all references to a symbol
GET	/api/code/dependencies/{path}	Get file import/dependent graph
GET	/api/code/callgraph?function=...	Get function call graph
GET	/api/code/impact?target=...	Analyze change impact
GET	/api/code/architecture	Get codebase overview
POST	/api/code/similar	Find similar code snippets
GET	/api/code/trait-impls?trait_name=...	Find types implementing a trait
GET	/api/code/type-traits?type_name=...	Find traits implemented by a type
GET	/api/code/impl-blocks?type_name=...	Get all impl blocks for a type

Auto-Sync with File Watcher

Keep the knowledge base updated automatically while coding:

# Start watching a project directory
curl -X POST http://localhost:8080/api/watch \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/project"}'

# Check watcher status
curl http://localhost:8080/api/watch

# Stop watching
curl -X DELETE http://localhost:8080/api/watch

The watcher automatically syncs .rs, .ts, .tsx, .js, .jsx, .py, .go files when modified. It ignores node_modules/, target/, .git/, __pycache__/, dist/, build/.

Code Exploration

Query the code graph instead of reading files directly:

# Semantic search across code
curl "http://localhost:8080/api/code/search?q=error+handling&language=rust&limit=10"

# Get symbols in a file (functions, structs, etc.)
curl "http://localhost:8080/api/code/symbols/src%2Flib.rs"

# Find all references to a symbol
curl "http://localhost:8080/api/code/references?symbol=AppState&limit=20"

# Get file dependencies (imports and dependents)
curl "http://localhost:8080/api/code/dependencies/src%2Fneo4j%2Fclient.rs"

# Get call graph for a function
curl "http://localhost:8080/api/code/callgraph?function=handle_request&depth=2&direction=both"

# Analyze impact before changing a file
curl "http://localhost:8080/api/code/impact?target=src/lib.rs&target_type=file"

# Get architecture overview
curl "http://localhost:8080/api/code/architecture"

# Find similar code patterns
curl -X POST http://localhost:8080/api/code/similar \
  -H "Content-Type: application/json" \
  -d '{"snippet": "async fn handle_error", "limit": 5}'

# Find all types implementing a trait
curl "http://localhost:8080/api/code/trait-impls?trait_name=Module"

# Find all traits implemented by a type
curl "http://localhost:8080/api/code/type-traits?type_name=Orchestrator"

# Get all impl blocks for a type
curl "http://localhost:8080/api/code/impl-blocks?type_name=Neo4jClient"

For Agents

Getting context before starting work

# Fetch your task context
curl http://localhost:8080/api/plans/$PLAN_ID/tasks/$TASK_ID/prompt

Recording decisions while working

curl -X POST http://localhost:8080/api/tasks/$TASK_ID/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Chose X over Y",
    "rationale": "Because..."
  }'

Notifying completion

curl -X POST http://localhost:8080/api/wake \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "'$TASK_ID'",
    "success": true,
    "summary": "Implemented feature X",
    "files_modified": ["src/foo.rs", "src/bar.rs"]
  }'

Configuration

Environment variables:

Variable	Default	Description
NEO4J_URI	bolt://localhost:7687	Neo4j connection URI
NEO4J_USER	neo4j	Neo4j username
NEO4J_PASSWORD	orchestrator123	Neo4j password
MEILISEARCH_URL	http://localhost:7700	Meilisearch URL
MEILISEARCH_KEY	orchestrator-meili-key-change-me	Meilisearch API key
WORKSPACE_PATH	.	Default workspace path
SERVER_PORT	8080	Server port
RUST_LOG	info	Log level

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR API                          │
│                    (localhost:8080)                          │
└─────────────────────────────┬───────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│    NEO4J      │     │  MEILISEARCH  │     │  TREE-SITTER  │
│   (7687)      │     │    (7700)     │     │   (in-proc)   │
│               │     │               │     │               │
│ • Code graph  │     │ • Code search │     │ • AST parsing │
│ • Plans       │     │ • Decisions   │     │ • Symbols     │
│ • Decisions   │     │ • Logs        │     │ • Complexity  │
│ • Relations   │     │               │     │               │
└───────────────┘     └───────────────┘     └───────────────┘

Development

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run -- serve

# Format code
cargo fmt

# Lint
cargo clippy