Install

One-liner — clone, build, and add to Claude Code:

git clone https://github.com/DevvGwardo/brain-mcp.git ~/brain-mcp && cd ~/brain-mcp && npm install && npm run build

Then add the MCP server to your Claude Code config. Copy and paste this into your terminal:

claude mcp add brain -- node ~/brain-mcp/dist/index.js

Or manually add to ~/.claude/settings.json:

{
  "mcpServers": {
    "brain": {
      "command": "node",
      "args": ["~/brain-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code. Done.

What is this?

Multiple Claude Code sessions can't talk to each other. They duplicate work, create merge conflicts, and have no way to coordinate.

Brain MCP fixes this. It gives every session access to a shared brain — messages, state, resource locks, and the ability to spawn new agents in split tmux panes.

"Add proper error handling with 3 agents"

That's all you need to say. Claude auto-splits the work, spawns parallel agents side by side, and coordinates through the brain.

Architecture

graph TB
    subgraph "Your Terminal (tmux)"
        A["Claude Code #1<br/><b>lead</b>"]
        B["Claude Code #2<br/><b>worker-a</b>"]
        C["Claude Code #3<br/><b>worker-b</b>"]
    end

    A -->|brain_wake| B
    A -->|brain_wake| C

    subgraph "Brain MCP"
        D[("SQLite WAL<br/>~/.claude/brain/brain.db")]
        E["Channels & DMs"]
        F["Shared State K/V"]
        G["Resource Locks"]
    end

    A <-->|stdio| D
    B <-->|stdio| D
    C <-->|stdio| D

    E --> D
    F --> D
    G --> D

    style A fill:#7C3AED,stroke:#5B21B6,color:#fff
    style B fill:#2563EB,stroke:#1D4ED8,color:#fff
    style C fill:#2563EB,stroke:#1D4ED8,color:#fff
    style D fill:#F59E0B,stroke:#D97706,color:#000

Each Claude Code session spawns its own brain-mcp process via stdio. All processes share the same SQLite database (WAL mode for safe concurrent access). Sessions in the same working directory auto-group into a room. Zero server management required.

Tools

Identity & Discovery

Messaging

Shared State

Resource Coordination

Agent Spawning

brain_wake layout options:

Agent Spawning

One agent can spawn others with brain_wake. Spawned agents:

• Open in visible tmux split panes (side by side by default)
• Run with --dangerously-skip-permissions for unattended execution
• Use claude -p (print mode) so they auto-exit when done — panes close cleanly
• Read their task from the brain's tasks channel automatically

sequenceDiagram
    participant Lead as Lead Agent
    participant Brain as Brain DB
    participant W1 as Worker 1
    participant W2 as Worker 2

    Lead->>Brain: brain_set("shared-context", ...)
    Lead->>Brain: brain_wake("worker-1", task)
    Lead->>Brain: brain_wake("worker-2", task)

    Brain-->>W1: Spawns in tmux pane
    Brain-->>W2: Spawns in tmux pane

    W1->>Brain: brain_register("worker-1")
    W2->>Brain: brain_register("worker-2")

    W1->>Brain: brain_get("shared-context")
    W2->>Brain: brain_get("shared-context")

    W1->>Brain: brain_claim("src/hooks/")
    W2->>Brain: brain_claim("src/api/")

    Note over W1,W2: Both work in parallel

    W1->>Brain: brain_post("hooks done")
    W1->>Brain: brain_release("src/hooks/")
    W1-->>W1: auto-exit, pane closes

    W2->>Brain: brain_post("api done")
    W2->>Brain: brain_release("src/api/")
    W2-->>W2: auto-exit, pane closes

    Lead->>Brain: brain_read() → sees both reports

Examples

Simple — just talk naturally

"Refactor the API routes with 2 agents"

"Add loading states to all components, use 3 agents"

"Review this codebase in parallel"

Add the Brain orchestration instructions to your CLAUDE.md and Claude will automatically use the brain tools when you mention parallel agents.

Manual — step by step

Session 1 — Architect

brain_register("architect")
brain_set(key="api_contract", value='{"users": "GET /api/users"}')
brain_post(content="Contract is set. Frontend: take users. Backend: take posts.")

Session 2 — Frontend

brain_register("frontend")
brain_read()                              # sees architect's message
brain_get(key="api_contract")             # reads the contract
brain_claim("src/pages/Users.tsx")        # locks the file
brain_dm(to="backend", content="What shape is the /users response?")

Session 3 — Backend

brain_register("backend")
brain_inbox()                             # sees frontend's question
brain_claim("src/api/posts.ts", ttl=300)  # auto-releases in 5 min
brain_post(content="Users response: { id, name, email }[]")

Claude Code Instructions

Add this to your project's CLAUDE.md so Claude automatically orchestrates when you say "with N agents":

## Brain MCP — Multi-Agent Orchestration

The `brain` MCP server enables multiple Claude Code sessions to communicate
and coordinate. When the user asks to parallelize work, use multiple agents,
split a task, or swarm something, use the brain tools automatically.

### How to orchestrate
1. `brain_register` with a name describing your role
2. Analyze the task and decide how to split it across agents
3. Read relevant files to build shared context
4. `brain_set` the shared context so spawned agents can read it
5. `brain_wake` each agent with a clear task
6. Monitor with `brain_read` until all agents report back
7. Post a final summary

### Rules
- Each agent gets different files — never assign the same file to two agents
- Use `brain_claim` before editing, `brain_release` after
- For 3+ agents, pass `layout: "tiled"` to `brain_wake`

Configuration

All configuration is through environment variables:

{
  "mcpServers": {
    "brain": {
      "command": "node",
      "args": ["~/brain-mcp/dist/index.js"],
      "env": {
        "BRAIN_SESSION_NAME": "worker-1",
        "BRAIN_ROOM": "my-project"
      }
    }
  }
}

Brain vs Built-in Teams

Development

npm run dev     # Watch mode
npm run build   # Build
npm start       # Run directly