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 12 languages
- Plan Management: Structured tasks with dependencies and constraints
- MCP Integration: 62 tools for Claude Code, OpenAI Agents, and Cursor
Documentation
Quick Start
1. Start the backends
cd {baseDir}
docker compose up -d neo4j meilisearch
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
