Get started
From install to first answer in four steps
A fresh install needs nothing but Python: everything is kept in one local file until you point it at real databases.
BBM-Atlas 1.0.0 is on PyPI, and its extension on the VS Code Marketplace and Open VSX.
- 1
Install
BBM-Atlas needs Python 3.11 or newer and installs from PyPI as one package. The core install is light; the local embedding model and the in-process LLM are optional extras (embeddings, llm).
terminalpip install bbm-atlas# With a local embedding model and an in-process LLM:pip install "bbm-atlas[embeddings,llm]" - 2
Start the API
With no .env, BBM-Atlas keeps everything in one local database file, so indexed repositories and learned facts survive restarts, with no database to set up. The CLI, your assistant and the web console all talk to this API.
terminalbbm-atlas serve# → 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 running API's MCP endpoint with Claude Code for this project. Your assistant can now search, trace impact, walk the graph and remember facts on its own, on the repositories you just indexed. Or install the Claude Code plugin, which brings a server of its own and the skills to use it. For Cursor, Zed, JetBrains and other clients, see MCP clients.
terminalbbm-atlas mcp install --url http://127.0.0.1:8000/mcp# Writes a bbm-atlas entry into ./.mcp.json# With API keys: add --api-key-env BBM_ATLAS_API_KEY
Use your own databases
When one file is not enough, point BBM-Atlas at Postgres, Neo4j, Qdrant and Redis. Every replica that shares them shares the same repositories.
export BBM_ATLAS_STORAGE_BACKEND=allexport BBM_ATLAS_POSTGRES_DSN=postgresql+psycopg://atlas:…@db:5432/atlasexport BBM_ATLAS_NEO4J_URI=bolt://graph:7687export BBM_ATLAS_NEO4J_PASSWORD=…export BBM_ATLAS_QDRANT_URL=http://vectors:6333export BBM_ATLAS_REDIS_URL=redis://cache:6379/0bbm-atlas serveOther MCP hosts
VS Code, Cursor and other hosts that speak HTTP connect to the running API. A host without HTTP can start its own stdio server: python -m bbm_atlas.cli mcp serve.
{ "servers": { "bbm-atlas": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } }}In VS Code
The BBM-Atlas extension installs and runs BBM-Atlas for you, indexes the workspace, and shows what a change affects from the cursor, with callers and callees on hover and @atlas in the chat. In Cursor, VSCodium or Devin Desktop, install it from Open VSX.

Every setting, serving a team, the editor and the Enterprise Edition are in the docs. Stuck, or want a hand setting it up for your team? Write to us.