probelabs/big-brain

BigBrain MCP Server

When your AI needs a bigger brain.

Overview

BigBrain is an MCP server that gives your AI an elegant exit when it gets stuck, loops, or loses context. It intelligently extracts relevant code and context, packages it cleanly, and operates in two modes:

• External AI Mode: Get fresh insights from external AI models like ChatGPT 5 Pro, Grok Heavy, or Claude Opus - then return with the solution to your original chat
• Multi-Agent Mode: Enable seamless AI-to-AI communication within systems like Claude Code for direct agent collaboration

Features

• Intelligent Context Extraction: Uses Probe to automatically discover and extract relevant code, dependencies, and context
• Dual Operation Modes:
  • External AI Mode: Round-trip workflow with clipboard integration for user-driven external consultation
  • Multi-Agent Mode: Direct AI-to-AI communication for automated agent collaboration
• Clean Context Packaging: Formats everything into minimal, structured prompt packs
• Multi-Model Support: Works with any AI but optimized for advanced models like ChatGPT 5 Pro, Grok Heavy, and Claude Opus
• File-Based Communication: Reliable agent-to-agent transfer in multi-agent systems
• Configurable Notifications: Optional sound and desktop notifications (can be disabled with flags)

Installation

Claude Code (Recommended)

claude mcp add -- npx -y @probelabs/big-brain@latest

Cursor & Other MCP Clients

Add to your MCP configuration file:

{
  "mcpServers": {
    "big-brain": {
      "command": "npx",
      "args": ["-y", "@probelabs/big-brain@latest"]
    }
  }
}

Usage Modes

BigBrain operates in two distinct modes depending on your workflow needs:

External AI Mode (Default)

For manual consultation with external AI models:

# Standard installation uses External AI Mode
claude mcp add -- npx -y @probelabs/big-brain@latest

Workflow:

1. Ask your AI to use BigBrain when stuck
2. BigBrain extracts code and copies to clipboard
3. Paste into external AI (ChatGPT 5 Pro, Grok Heavy, Claude Opus)
4. Return with solution to original chat

Multi-Agent Mode

For automated AI-to-AI communication in systems like Claude Code:

# Enable loop mode with custom agent prompt
npx @probelabs/big-brain --loop "Now call research-agent to investigate this issue"

Workflow:

1. AI uses BigBrain with --loop flag and custom prompt
2. BigBrain extracts code and saves to file (no clipboard)
3. Returns instructions for the next agent to read the file
4. Seamless automated agent collaboration

When to Use Each Mode

Quick Start

External AI Mode

1. Ask AI to use BigBrain

When your AI gets stuck, loops, or loses context:

Ask BigBrain to help me with this React component issue

2. Get External Advice

BigBrain extracts code and copies everything to clipboard. Open fresh AI chat, paste, and get the solution.

3. Return with Solution

Copy the external AI's response and return to your original chat. Paste the solution to continue with fresh insights.

Multi-Agent Mode

1. AI Initiates with Loop Flag

Your AI system uses BigBrain with a custom agent prompt:

AI calls: bigbrain --loop "Now call research-agent to investigate this issue"

2. Direct Agent Communication

BigBrain responds with file path and instructions for the next agent to read and process the context.

3. Automated Continuation

The designated agent reads the file and continues the workflow without human intervention.

Configuration Options

Available Flags

BigBrain supports several command-line flags to customize behavior:

{
  "mcpServers": {
    "big-brain": {
      "command": "npx",
      "args": [
        "-y", "@probelabs/big-brain@latest",
        "--disable-sound",
        "--disable-notification"
      ]
    }
  }
}

Flag Reference:

• --loop "custom prompt": Enable multi-agent mode with custom agent instruction
• --disable-sound: Disable sound notifications
• --disable-notification: Disable desktop notifications

Multi-Agent Configuration Example

For systems like Claude Code that need automated agent communication:

{
  "mcpServers": {
    "big-brain": {
      "command": "npx", 
      "args": [
        "-y", "@probelabs/big-brain@latest",
        "--loop", "Now call research-agent to investigate this issue",
        "--disable-sound",
        "--disable-notification"
      ]
    }
  }
}

How BigBrain Works

External AI Mode Process

1. AI Preparation: Your AI prepares a comprehensive question with all needed context and details
2. Intelligent Extraction: BigBrain uses Probe to automatically scan and extract relevant code, dependencies, and context
3. Clean Packaging: Everything is formatted into a minimal, paste-ready prompt pack and copied to your clipboard
4. External Consultation: You paste the context pack into a fresh AI chat (ChatGPT 5 Pro, Grok Heavy, Claude Opus, etc.) to get analysis and solutions
5. Return Journey: Copy the external AI's response and paste it back into your original chat to continue with fresh insights

Multi-Agent Mode Process

1. Agent Initiation: AI system calls BigBrain with --loop flag and custom agent prompt
2. Intelligent Extraction: BigBrain uses Probe to automatically extract relevant code and context
3. File-Based Packaging: Context is saved to a temporary file in structured XML format
4. Agent Instruction: BigBrain responds with the custom prompt and file path for the next agent
5. Direct Handoff: The designated agent reads the file and continues processing without human intervention

Why Both Modes Work

External AI Mode Benefits:

• Breaks Context Loops: Fresh AI session without chat history noise
• Leverages Advanced Models: Use the best AI for complex analysis
• Human Oversight: Manual control over consultation process
• Model Flexibility: Choose the right AI for each specific problem

Multi-Agent Mode Benefits:

• Automated Workflows: No human intervention required
• Reliable Transfer: File-based communication eliminates clipboard dependencies
• Agent Coordination: Custom prompts guide specific agent actions
• Seamless Integration: Built for systems like Claude Code with multiple AI agents

Shared Benefits:

• Intelligent Context: Probe ensures all relevant code is included automatically
• Clean Separation: Focused context without noise
• Maintains Workflow: Continue original work with fresh insights

Optional: Automate BigBrain Usage

Add this to your CLAUDE.md file so your AI automatically knows when to use BigBrain:

# BigBrain Integration
Whenever you get stuck and can't find a solution - just ask BigBrain MCP for advice.

Development

Local Development Setup

git clone https://github.com/probelabs/big-brain.git
cd big-brain
npm install
npm run build

Development Commands

npm run build        # Build the project
npm run watch        # Watch mode for development
npm run inspector    # Test with MCP Inspector

The MCP Inspector provides a browser-based interface for testing and debugging the server.

Requirements

• Node.js 16 or higher
• npm or yarn

Technical Details

Built on Probe

BigBrain leverages Probe for intelligent code extraction. When your AI mentions specific files or functions, Probe automatically discovers and includes all related dependencies, types, and context - no manual file specification required.

Supported File Types

BigBrain works with all common programming languages and file types:

• TypeScript/JavaScript (.ts, .tsx, .js, .jsx)
• Python (.py)
• Rust (.rs)
• Go (.go)
• JSON (.json)
• Markdown (.md)
• And many more...

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issue tracker.