- last_validated
- 2026-03-16
Agent Brain
A RAG-based (Retrieval-Augmented Generation) document indexing and semantic search system for AI agents and applications. Agent Brain enables intelligent querying of documentation and source code using natural language.
Overview
Agent Brain provides AI-first document and code search through a Claude Code plugin with skills, commands, and agents. Use slash commands to search, agents for complex research tasks, and skills for intelligent query optimization.
Quick Start (Claude Code Plugin)
1. Install the Plugin
# 1. Add the Agent Brain marketplace (the repo is a plugin marketplace)
claude plugins marketplace add SpillwaveSolutions/agent-brain
# 2. Install the plugin from that marketplace
claude plugins install agent-brain@agent-brain-marketplace
Installing a Claude Code plugin does not use
pip. The plugin is installed through the marketplace above; the underlying Python packages (agent-brain-rag,agent-brain-cli) are installed for you by the/agent-brain-setupwizard (or manually viapip— see CLI Usage).
Other hosts
The same plugin installs into Codex, Cursor, Grok Build, and OpenCode through the CLI. Each command converts the shared payload into the host's native layout and, with --with-mcp, registers the MCP server in that host's config file.
pip install agent-brain-rag agent-brain-cli agent-brain-ag-mcp
agent-brain install-agent --agent codex --with-mcp # .codex/skills/agent-brain + AGENTS.md; MCP in ~/.codex/config.toml
agent-brain install-agent --agent cursor --with-mcp # .cursor/plugins/agent-brain + .cursor/rules; MCP in .cursor/mcp.json
agent-brain install-agent --agent grok --with-mcp # .grok/plugins/agent-brain; zero-config Claude load, MCP in .mcp.json
agent-brain install-agent --agent opencode --with-mcp # .opencode/plugins/agent-brain; MCP in opencode.json
A conforming Agent Plugins 1.0 client reads agent-brain-plugin/plugin.json, skills/, and mcp.json directly. See docs/HOSTS.md for the manifest each host reads.
2. Set Up Your Project
In Claude Code, run:
/agent-brain-setup
This interactive wizard will:
- Install the Python packages (
agent-brain-rag,agent-brain-cli) - Configure your API keys
- Initialize the project
- Start the server
- Index your documentation
3. Search with Commands
/agent-brain-search "how does authentication work"
That's it! The plugin handles everything automatically.
Plugin Commands
Search Commands
Server Commands
Setup Commands
Plugin Agents
Agent Brain includes three intelligent agents for complex tasks:
Example Agent Interaction
You: "Research how authentication is implemented across the codebase"
Research Assistant:
- Searches documentation for auth concepts
- Queries code for auth-related functions
- Uses graph mode to find dependencies
- Synthesizes comprehensive answer with references
Plugin Skills
Skills provide intelligent context to Claude for optimal searching:
When you ask about documentation or code, Claude automatically uses the skill to:
- Choose the best search mode for your query
- Set appropriate parameters (top_k, threshold, alpha)
- Interpret and synthesize results
Search Modes
Pluggable Providers
Agent Brain supports multiple providers for embeddings and summarization:
Embedding Providers
Summarization Providers
Fully Local Mode
Run completely offline with Ollama:
/agent-brain-providers
# Select Ollama for both embeddings and summarization
Features
Code Search
- 10 Programming Languages: Python, TypeScript, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift
- AST-Aware Chunking: Tree-sitter parsing preserves code structure
- LLM Summaries: AI-generated descriptions improve semantic search
- Language Filtering: Filter results by programming language
GraphRAG (Knowledge Graph)
- Entity and relationship extraction
- Dependency-aware queries ("What calls X?")
- Code structure visualization
Multi-Instance Architecture
- Per-project isolated servers
- Automatic port allocation
- Work on multiple projects simultaneously
Project Structure
agent-brain/
├── agent-brain-plugin/ # Claude Code plugin (primary interface)
│ ├── commands/ # 30 slash commands
│ ├── agents/ # 3 intelligent agents
│ └── skills/ # 2 context skills
├── agent-brain-server/ # FastAPI backend
├── agent-brain-cli/ # CLI tool (used by plugin)
└── docs/ # Documentation
Documentation
Getting Started
- Quick Start - Get running in minutes
- Plugin Guide - Complete plugin documentation
- User Guide - Detailed usage guide
- MCP Quickstart - Use Agent Brain over MCP in ~5 minutes
- Project Setup: Plugin + Skills + MCP - Wire all three into one project
Reference
- API Reference - REST API documentation
- MCP User Guide - MCP server: 16 tools, resources, prompts, OAuth
- Configuration - All configuration options
- Provider Configuration - Provider setup
- Integrations - Connect agent-brain-mcp to LLM frameworks + editors
Architecture
- Architecture Overview - System design
- GraphRAG Guide - Knowledge graph features
- Code Indexing - AST-aware chunking
CLI Usage (Alternative)
While the plugin is the recommended interface, you can also use the CLI directly:
# Install
pip install agent-brain-rag agent-brain-cli
# Initialize and start
agent-brain init # auto-generates a per-project API key
agent-brain start --daemon
# Index and query
agent-brain index /path/to/docs --include-code
agent-brain query "authentication" --mode hybrid
Note on authentication. As of the next release, every data endpoint requires
X-API-Key.agent-brain initwrites a 32-byte urlsafe key into.agent-brain/config.json(mode0o600); the CLI andagent-brain-mcppick it up automatically. Pass--no-api-keytoagent-brain initfor the legacy no-auth experience on127.0.0.1. The server refuses to start on any non-loopback bind without a key set. Seedocs/CHANGELOG.mdunder the unreleased entry for the full design (Issue #179).
Development
Prerequisites
- Python 3.10+
- Poetry (dependency management)
- Task (task runner)
Setup
git clone https://github.com/SpillwaveSolutions/agent-brain.git
cd agent-brain
task install
Running Tests
task test # All tests
task before-push # Full quality check
Technology Stack
- Plugin: Claude Code slash commands, agents, skills
- Server: FastAPI + Uvicorn
- Vector Store: ChromaDB (HNSW, cosine similarity)
- BM25 Index: LlamaIndex BM25Retriever
- Graph Store: SimplePropertyGraphStore / Kuzu
- Embeddings: OpenAI or Ollama
- Summarization: Claude, GPT-5, Gemini, Grok, or Ollama
- AST Parsing: tree-sitter (10 languages)
- CLI: Click + Rich
- Build System: Poetry
Contributing
See the Developer Guide for setup instructions.
Before pushing changes, always run:
task before-push
License
MIT License - see LICENSE file for details.
