Project Orchestrator

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.

Security Scan

The skill largely matches its stated purpose (orchestrating agents with Neo4j/Meilisearch/Tree-sitter) but contains multiple incoherences and risky defaults — notably it ships source code without an install spec, fails to declare required credentials, and documents an unauthenticated HTTP API and file-watcher that can read arbitrary local paths.

Purpose & Capability

The name/description (Neo4j + Meilisearch + Tree-sitter orchestrator) aligns with the included source (Rust code for neo4j/meilisearch/tree-sitter, many API/mcp handlers) and the declared required binaries (docker, cargo). However the registry metadata / SKILL.md claim 'required env vars: none' while docs and docker-compose clearly show NEO4J and MEILISEARCH credentials/configuration — an omission that is inconsistent and worth flagging. Also the registry says 'instruction-only' (no install spec) even though the skill bundle contains full source and build instructions.

Instruction Scope

SKILL.md and the docs instruct running 'docker compose up' and 'cargo build' and using HTTP endpoints (e.g., POST /api/sync with absolute paths) and a file watcher to auto-sync directories. The API reference explicitly states 'the API does not require authentication' which means the service will, by default, expose operations that can read and index arbitrary filesystem paths and record decisions/plans without auth. For an agent that can call local endpoints this grants broad access to host files and metadata — behavior that goes beyond a simple helper and requires careful operational controls.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but the repository includes full source and a Docker Compose file with clear build/run instructions (cargo build, docker compose up). This is lower-risk than an arbitrary remote download, since source is bundled, but it's inconsistent with the 'instruction-only' label and means compilation/run happens locally (needs cargo/docker present).

Credentials

The skill declares no required env vars, yet docs and docker-compose use several sensitive environment values (NEO4J_URI/USER/PASSWORD, MEILISEARCH_URL/KEY, NEO4J_AUTH, MEILI_MASTER_KEY). The docker-compose provides default passwords (e.g., orchestrator123, orchestrator-meili-key-change-me). Requiring access to these credentials is proportional to the stated purpose, but omitting them from declared requirements and shipping default cleartext credentials is an operational and security concern.

Persistence & Privilege

The skill does not request 'always: true' (good), but running it starts an HTTP API, file watcher, and an MCP server exposing 100+ tools to connected agent clients. Combined with the documented default of 'no authentication' and the file-watcher/sync endpoints accepting arbitrary paths, this produces an elevated persistent local attack surface: a running orchestrator could be used (accidentally or maliciously) to index or expose host files and project secrets unless the user explicitly secures it (network access controls, auth reverse-proxy, limiting watched paths).

What to consider before installing

What to consider before installing: - This bundle is coherent with its stated functionality (Neo4j + Meilisearch + parsing) but contains full source code and explicit run instructions; it will compile/run on your machine (cargo, docker required). - The docs state the HTTP API is unauthenticated by default. If you run this service locally it will expose endpoints that accept absolute filesystem paths (sync/watch) and can read/index your code. Treat this like running any local service that can access files: only run it in a controlled environment. - The repository and docker-compose include default credentials (NEO4J_PASSWORD, MEILI_MASTER_KEY). Change these before exposing services, and do not reuse them for other systems. - Before running: audit the source (or have someone you trust audit it), restrict what directories are watched/synced, run in an isolated environment/container, and front the service with authentication (reverse proxy or local firewall rules). If you will expose it to other processes/agents, require authentication for the API and limit network access. - If you cannot or will not audit the code, or you do not have a segregated environment to run services that can read arbitrary host paths, do not install. At minimum, verify the code paths that handle /api/sync, /api/watch, and MCP tool handlers to confirm they enforce expected access controls.

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 <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