🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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.

Versionv0.2.0
Downloads3,436
Stars⭐ 3
TERMINAL
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

  • 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

  • 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 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  \
      --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/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

    πŸ’‘ 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/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  \
      --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 |