curl -fsSL https://raw.githubusercontent.com/DevvGwardo/brain-mcp/main/install.sh | bash

git clone https://github.com/DevvGwardo/brain-mcp.git
cd brain-mcp
npm install
npm run build
pip install -e .
hermes mcp add brain --command node --args "$PWD/dist/index.js"

hermes mcp list | grep brain
hermes mcp test brain
hermes-brain --help

brain_wake({ task: "...", layout: "headless" })

hermes-brain "Build a REST API with auth, users, and posts" \
  --agents api-routes auth-layer db-models tests

# Auto-named agents
hermes-brain "Add error handling to the whole codebase"

# Mix models per task
hermes-brain "Build a game" --agents engine ui store --model claude-sonnet-4-5

# Cheap model for boilerplate
hermes-brain "Generate 10 test files" --model claude-haiku-4-5

# JSON pipeline with multiple phases
hermes-brain --config pipeline.json

hermes> Use register, then wake to spawn 3 agents
        that each refactor a different module.

graph TB
    subgraph "Python Conductor"
        CLI["hermes-brain CLI"]
        ORCH["Orchestrator<br/><small>spawn · wait · gate · retry</small>"]
    end

    subgraph "Hermes Agents"
        direction LR
        H1["Agent 1<br/><small>hermes -q</small>"]
        H2["Agent 2<br/><small>hermes -q</small>"]
        H3["Agent 3<br/><small>hermes -q</small>"]
    end

    CLI --> ORCH
    ORCH -->|spawn| H1
    ORCH -->|spawn| H2
    ORCH -->|spawn| H3

    subgraph "Brain (shared SQLite)"
        DB[("brain.db")]
        PULSE["Heartbeats"]
        MX["Mutex Locks"]
        KV["Shared State"]
        CON["Contracts"]
        MEM["Memory"]
        PLAN["Task DAG"]
    end

    ORCH <--> DB
    H1 <--> DB
    H2 <--> DB
    H3 <--> DB

    subgraph "Integration Gate"
        GATE["tsc · mypy · cargo · go vet"]
        ROUTE["DM errors → agents"]
    end

    ORCH --> GATE
    GATE --> ROUTE
    ROUTE -.->|DM| H1
    ROUTE -.->|DM| H2

    style CLI fill:#9333EA,stroke:#7C3AED,color:#fff
    style ORCH fill:#9333EA,stroke:#7C3AED,color:#fff
    style H1 fill:#3B82F6,stroke:#2563EB,color:#fff
    style H2 fill:#10B981,stroke:#059669,color:#fff
    style H3 fill:#F59E0B,stroke:#D97706,color:#000
    style DB fill:#1E293B,stroke:#334155,color:#fff
    style GATE fill:#EF4444,stroke:#DC2626,color:#fff

graph TB
    subgraph "External Clients"
        HERMES["Hermes CLI"]
        CLAUDE["Claude Code"]
        ANY["Any MCP Client"]
    end

    subgraph "brain-mcp (Node.js)"
        SERVER["src/index.ts<br/>MCP Request Router"]
        CONDUCTOR["brain-conductor<br/>Zero-token Orchestration CLI"]
        GATE["src/gate.ts<br/>Integration Gate"]
    end

    subgraph "pi-agent-core Runtime"
        PI_CORE["src/pi-core-agent.ts<br/>In-process Agent Runner"]
        PI_CORE_TOOLS["src/pi-core-tools.ts<br/>14 Brain Tools as AgentTools"]
        PI_AGENT["pi-agent-core Agent<br/>model + tools + events"]
    end

    subgraph "BrainDB (SQLite)"
        DB[("brain.db<br/>sessions, state, messages,<br/>claims, contracts, memory")]
    end

    HERMES & CLAUDE & ANY --> SERVER
    SERVER <--> DB
    SERVER --> CONDUCTOR
    CONDUCTOR --> PI_CORE
    PI_CORE --> PI_CORE_TOOLS
    PI_CORE --> PI_AGENT
    PI_CORE_TOOLS --> DB
    PI_AGENT -->|beforeToolCall<br/>pulse| DB
    CONDUCTOR --> GATE
    GATE -->|DM errors| CONDUCTOR

    style HERMES fill:#FF6B6B,stroke:#DC2626,color:#fff
    style CLAUDE fill:#3B82F6,stroke:#2563EB,color:#fff
    style ANY fill:#7C3AED,stroke:#6D28D9,color:#fff
    style SERVER fill:#1E293B,stroke:#334155,color:#fff
    style CONDUCTOR fill:#9333EA,stroke:#7C3AED,color:#fff
    style GATE fill:#EF4444,stroke:#DC2626,color:#fff
    style PI_CORE fill:#10B981,stroke:#059669,color:#fff
    style PI_CORE_TOOLS fill:#059669,stroke:#047857,color:#fff
    style PI_AGENT fill:#06B6D4,stroke:#0891B2,color:#fff
    style DB fill:#1E293B,stroke:#334155,color:#fff

hermes-brain <task> [options]

{
  "task": "Build a todo app",
  "model": "claude-sonnet-4-5",
  "gate": true,
  "max_gate_retries": 3,
  "phases": [
    {
      "name": "foundation",
      "parallel": true,
      "agents": [
        { "name": "types",  "files": ["src/types/"], "task": "Define all TS types" },
        { "name": "db",     "files": ["src/db/"],    "task": "Set up Prisma schema" }
      ]
    },
    {
      "name": "feature",
      "parallel": true,
      "agents": [
        { "name": "api",    "files": ["src/api/"],   "task": "REST endpoints" },
        { "name": "ui",     "files": ["src/ui/"],    "task": "React components" }
      ]
    },
    {
      "name": "quality",
      "parallel": true,
      "agents": [
        { "name": "tests",  "task": "Write unit + integration tests" }
      ]
    }
  ]
}

sequenceDiagram
    participant O as Orchestrator
    participant C as Compiler
    participant DB as Brain DB
    participant A as Agent

    O->>C: Run tsc / mypy / cargo / go vet
    C-->>O: Errors with file:line:message

    O->>DB: Query: who claimed this file?
    DB-->>O: Agent X owned src/api/routes.ts

    O->>A: DM: "Fix these errors in your files"
    Note over A: Agent reads DM on next pulse
    Note over A: Fixes code, pulses done

    O->>C: Re-run compiler
    C-->>O: Clean
    O->>DB: Record metrics

graph LR
    subgraph "Fleet"
        direction TB
        HA["Hermes Agent<br/><small>fast local inference</small>"]
        CC["Claude Code<br/><small>deep reasoning</small>"]
        MM["MiniMax<br/><small>cheap boilerplate</small>"]
    end

    subgraph "Brain"
        DB[("brain.db")]
    end

    HA <--> DB
    CC <--> DB
    MM <--> DB

    style HA fill:#F59E0B,stroke:#D97706,color:#000
    style CC fill:#9333EA,stroke:#7C3AED,color:#fff
    style MM fill:#3B82F6,stroke:#2563EB,color:#fff
    style DB fill:#1E293B,stroke:#334155,color:#fff

brain_wake({ task: "...", cli: "hermes", layout: "headless" })
brain_wake({ task: "...", cli: "claude", layout: "horizontal" })

node benchmark.mjs        # SQLite direct layer (1000 iterations)
node benchmark-mcp.mjs    # MCP tool layer (30 iterations per tool)

graph TB
    subgraph "MCP Clients"
        HA["hermes sessions"]
        CC["claude sessions"]
        PY["Python orchestrator"]
    end

    subgraph "MCP Layer"
        M1["brain-mcp<br/><small>stdio server</small>"]
    end

    subgraph "Python API"
        PYDB["hermes.db.BrainDB<br/><small>direct SQLite access</small>"]
    end

    subgraph "Storage"
        DB[("~/.claude/brain/brain.db<br/><small>SQLite WAL</small>")]
    end

    HA --> M1
    CC --> M1
    PY --> PYDB
    M1 --> DB
    PYDB --> DB

    subgraph "Tables"
        T1["sessions · messages · dms"]
        T2["state · claims · contracts"]
        T3["memory · plans · metrics"]
        T4["context_ledger · checkpoints"]
    end

    DB --- T1
    DB --- T2
    DB --- T3
    DB --- T4

    style HA fill:#F59E0B,stroke:#D97706,color:#000
    style CC fill:#9333EA,stroke:#7C3AED,color:#fff
    style PY fill:#3776AB,stroke:#2C5F8D,color:#fff
    style DB fill:#10B981,stroke:#059669,color:#fff