Installation

Install a specific version

curl -fsSL https://…/install.sh | sh -s -- --version 0.0.14

Install without the embedded frontend (lighter)

curl -fsSL https://…/install.sh | sh -s -- --no-frontend

Custom install directory

curl -fsSL https://…/install.sh | sh -s -- --install-dir /usr/local/bin ```

---

Docker

```bash

Download and install the .deb package

curl -LO https://github.com/this-rs/project-orchestrator/releases/latest/download/project-orchestrator_0.0.14-1_amd64.deb sudo dpkg -i project-orchestrator_0.0.14-1_amd64.deb

Download and install the .rpm package

curl -LO https://github.com/this-rs/project-orchestrator/releases/latest/download/project-orchestrator-0.0.14-1.x86_64.rpm sudo rpm -i project-orchestrator-0.0.14-1.x86_64.rpm ```

---

Build from Source

```bash git clone https://github.com/this-rs/project-orchestrator.git cd project-orchestrator cargo build --release

Quick Start

Example: Safe Modification Protocol

A protocol that ensures every non-trivial code change goes through proper impact analysis, topology checks, and documentation — using the full knowledge fabric:

protocol(action: "compose", project_id: "...",
  name: "safe-modification",
  category: "business",
  states: [
    { name: "gather-context",  state_type: "start",
      description: "Load notes, decisions, propagated context, active RFCs" },
    { name: "analyze-impact",  state_type: "intermediate",
      description: "Run analyze_impact + get_file_co_changers on target files" },
    { name: "check-topology",  state_type: "intermediate",
      description: "Verify new imports don't violate architectural rules" },
    { name: "check-risks",     state_type: "intermediate",
      description: "Evaluate risk via get_node_importance — PageRank, betweenness, churn" },
    { name: "implement",       state_type: "intermediate",
      description: "Make changes with full awareness of impact and constraints" },
    { name: "verify",          state_type: "intermediate",
      description: "Run tests + re-check topology for new violations" },
    { name: "document",        state_type: "intermediate",
      description: "Create notes, record decisions, link AFFECTS to changed files" },
    { name: "done",            state_type: "terminal",
      description: "Changes are safe, tested, and documented" }
  ],
  transitions: [
    { from_state: "gather-context",  to_state: "analyze-impact",  trigger: "context_loaded" },
    { from_state: "analyze-impact",  to_state: "check-topology",  trigger: "impact_assessed" },
    { from_state: "check-topology",  to_state: "check-risks",     trigger: "topology_ok" },
    { from_state: "check-topology",  to_state: "gather-context",  trigger: "topology_violation",
      guard: "New imports violate architectural rules — rethink the approach" },
    { from_state: "check-risks",     to_state: "implement",       trigger: "risks_acceptable" },
    { from_state: "check-risks",     to_state: "gather-context",  trigger: "high_risk",
      guard: "Critical risk score — need a different approach" },
    { from_state: "implement",       to_state: "verify",          trigger: "changes_made" },
    { from_state: "verify",          to_state: "document",        trigger: "verification_passed" },
    { from_state: "verify",          to_state: "implement",       trigger: "verification_failed" },
    { from_state: "document",        to_state: "done",            trigger: "documented" }
  ],
  relevance_vector: { phase: 0.5, structure: 0.7, domain: 0.5, resource: 0.5, lifecycle: 0.5 }
)

Example: Knowledge Maintenance Protocol

A system protocol that runs weekly to keep the knowledge fabric healthy:

protocol(action: "compose", project_id: "...",
  name: "knowledge-maintenance",
  category: "system",
  states: [
    { name: "audit",           state_type: "start",
      description: "audit_gaps — find orphan notes, decisions without AFFECTS, unlinked commits" },
    { name: "health-check",    state_type: "intermediate",
      description: "get_health — hotspots, risks, homeostasis, neural metrics" },
    { name: "decay-synapses",  state_type: "intermediate",
      description: "Gentle decay (0.03) to prune dead connections — NEVER > 0.1 per pass" },
    { name: "update-scores",   state_type: "intermediate",
      description: "Recalculate staleness, energy, and fabric fusion scores" },
    { name: "review-stale",    state_type: "intermediate",
      description: "Find stale notes — confirm, invalidate, or supersede" },
    { name: "report",          state_type: "terminal",
      description: "persist_health_report — saves as note with delta vs. previous report" }
  ],
  transitions: [
    { from_state: "audit",           to_state: "health-check",    trigger: "audit_done" },
    { from_state: "health-check",    to_state: "decay-synapses",  trigger: "health_assessed" },
    { from_state: "decay-synapses",  to_state: "update-scores",   trigger: "decay_applied" },
    { from_state: "update-scores",   to_state: "review-stale",    trigger: "scores_updated" },
    { from_state: "review-stale",    to_state: "report",          trigger: "review_done" }
  ],
  relevance_vector: { phase: 0.75, structure: 0.3, domain: 0.5, resource: 0.3, lifecycle: 0.8 }
)

Full protocol guide: See Protocols — Building a Safe, Self-Aware Setup for detailed step-by-step instructions on what the agent should do at each state, how to set up hierarchical protocols, auto-triggers, and a recommended production suite.

---

2. Configure your AI tool

Add to your MCP configuration (e.g., ~/.claude/mcp.json):

{
  "mcpServers": {
    "project-orchestrator": {
      "command": "mcp_server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "orchestrator123",
        "MEILISEARCH_URL": "http://localhost:7700",
        "MEILISEARCH_KEY": "orchestrator-meili-key-change-me",
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}

Note: NATS_URL enables real-time event sync between the MCP server and other instances (desktop app, other agents). Without it, CRUD events from MCP tools won't propagate to the rest of the system. If some env vars are not forwarded by your AI tool, the MCP server also reads config.yaml as a fallback (see Configuration).

Configuration

The server uses a layered configuration system: env vars > config.yaml > defaults.

Copy and edit config.yaml at the project root:

server:
  port: 8080                    # SERVER_PORT

neo4j:
  uri: "bolt://localhost:7687"  # NEO4J_URI
  user: "neo4j"                 # NEO4J_USER
  password: "orchestrator123"   # NEO4J_PASSWORD

meilisearch:
  url: "http://localhost:7700"              # MEILISEARCH_URL
  key: "orchestrator-meili-key-change-me"   # MEILISEARCH_KEY

nats:
  url: "nats://localhost:4222"  # NATS_URL — inter-process event sync

chat:
  default_model: "claude-opus-4-6"  # CHAT_DEFAULT_MODEL

Why NATS? The MCP server runs as a separate process (spawned by Claude Code). NATS is the pub/sub bridge that propagates CRUD events and chat messages between the MCP server, the HTTP backend, and the desktop app. Without NATS, each instance works in isolation.

---

API-only (lighter, no frontend)

docker pull ghcr.io/this-rs/project-orchestrator:latest-api

Or use Docker Compose with all services (Neo4j, Meilisearch, NATS):

---

orch — CLI shorthand

Integrations

---

Understand module boundaries before refactoring

code(action: "get_communities", project_slug: "my-project")