Project Orchestrator
by @reversteam
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.
clawhub install project-orchestratorπ About This Skill
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
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/projectVia 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/projectsSync a project
curl -X POST http://localhost:8080/api/projects/embryon/syncSearch 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 \
--desc "Implement MatMul Metal shader"orch task add \
--plan \
--desc "Add attention layer GPU support" \
--depends
Get context for an agent
# JSON context
orch context --plan --task Ready-to-use prompt
orch context --plan --task --prompt
Record decisions
orch decision add \
--task \
--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/watchStop 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 testRun with debug logging
RUST_LOG=debug cargo run -- serveFormat code
cargo fmtLint
cargo clippy
π‘ Examples
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/projectsSync a project
curl -X POST http://localhost:8080/api/projects/embryon/syncSearch 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 \
--desc "Implement MatMul Metal shader"orch task add \
--plan \
--desc "Add attention layer GPU support" \
--depends
Get context for an agent
# JSON context
orch context --plan --task Ready-to-use prompt
orch context --plan --task --prompt
Record decisions
orch decision add \
--task \
--desc "Use shared memory for tile-based MatMul" \
--rationale "Better cache locality, 2x performance improvement"
Search past decisions
orch decision search "memory management GPU"
βοΈ 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 |