Get started
From clone to first answer in four steps
A fresh checkout needs nothing but Python: storage runs in memory until you point it at real databases.
- 1
Install
BBM-Atlas needs Python 3.11 or newer. The core install is light; the local embedding model and the in-process LLM are optional extras (embeddings, llm).
terminalgit clone https://github.com/TheAmitChandra/BBM-Atlas.gitcd BBM-Atlaspip install -e ".[dev]" - 2
Start the API
With no .env, everything runs in-process on hermetic in-memory stores: no database to set up. The CLI, the MCP server and the web console all talk to this API.
terminalpython -m uvicorn bbm_atlas.main:app# → http://localhost:8000 (the web console is at /console/) - 3
Index and ask
In another shell, index a repository and query it. Indexing prints the repository's id; later runs re-parse only the files that changed.
terminalbbm-atlas index ./my-repo --name my-repoREPO=<repository_id>bbm-atlas search $REPO "how does checkout work?"bbm-atlas impact $REPO shop.cart.checkout --max-depth 3 - 4
Connect your assistant
Register the MCP server with Claude Code for this project. Your assistant can now search, trace impact, walk the graph and remember facts on its own.
terminalbbm-atlas mcp install --host claude# Writes a bbm-atlas entry into ./.mcp.json
Run the full stack
Postgres, Neo4j, Qdrant, Redis and the API with Docker Compose. Every port is published on 127.0.0.1 only.
cp .env.example .env# Set POSTGRES_PASSWORD, NEO4J_PASSWORD, REDIS_PASSWORD# and QDRANT_API_KEY in .env (compose refuses to start without them)docker compose up -dOther MCP hosts
Cursor, JetBrains and other hosts take the same entry: run the server with the Python that has BBM-Atlas installed.
{ "mcpServers": { "bbm-atlas": { "command": "python", "args": ["-m", "bbm_atlas.cli", "mcp", "serve"] } }}Go deeper: every subsystem has an as-built specification.