BBM-Atlas for VS Code
What calls this? What breaks if I change it? Where is the code about X? BBM-Atlas reads your code into a
knowledge graph of what calls, imports and inherits from what, and answers in the editor. It also gives your AI
assistant the same answers, through MCP.
Learn more at atlas.byteblendmatrix.com; the extension's guide, with every
setting, is in the documentation.
Getting started
- Install the extension and open a project.
- BBM-Atlas runs on Python 3.11 or newer. The extension uses the interpreter the Python extension has selected,
or
python on your PATH. If BBM-Atlas is not installed there yet, the extension offers to install it with
pip, in a terminal you can watch.
- It starts BBM-Atlas on a local port, indexes your workspace in the background, and stops BBM-Atlas when you
close the window. The status bar shows BBM-Atlas: indexed when it is ready.
Features
- Analyze Impact. Right-click inside a function, method or class, or click the Impact code lens above it.
The Impact view lists everything that depends on it:
- grouped by distance (direct callers first, then two hops away, and so on);
- each with its relationship and file, one click from its source;
- with the tests that cover it, if you turn that on.
- Search. BBM-Atlas: Search… answers questions such as where are sessions refreshed?. It ranks
results from four sources: the code's structure, BBM-Atlas's memory of it, the graph, and semantic similarity.
Choosing a result opens it at its line; its thumbs say whether it was what you were looking for, and results you
rate count for more, or less, in later answers.
- Facts. Note what the code doesn't say - money is kept in cents, this module is being replaced - with
BBM-Atlas: Remember… (or right-click a selection). The Facts view lists each folder's notes; BBM-Atlas's
brief and your AI assistants know them too.
- Callers and callees on hover. Hover a function's name, or a call to it, to see who calls it and what it
calls, each a click from its line, with links to analyse its impact or open it in the graph.
- The graph, in the editor. Right-click inside a function or class and choose Show Graph Here: a panel
beside your code draws it with what it calls, imports and inherits from, and what does so to it. Double-click a
node to show its neighbours, press Enter to open it, scroll to zoom. Impact and Graph Insights items have a
Show Graph button too. The graph comes back when VS Code restarts, with what you had expanded.
- Graph Insights. How the code hangs together, in a view of its own:
- Find Path From Here To… shows the chain of calls and imports joining the symbol at the cursor to one you
pick, each step saying which way it runs;
- Show Import Cycles lists the modules that import each other round in a circle;
- Show Most-Connected Symbols lists the symbols the most code leans on - the riskiest to change.
Every item opens at its line.
- Show in Graph Explorer. Opens the symbol at the cursor in the web console's graph view, inside VS Code.
- Repositories. The BBM-Atlas view in the activity bar lists the indexed folders with their symbol and file
counts, and can re-index or remove them. Saving a file re-indexes its folder; only changed files are parsed
again.
- @atlas in the chat. Ask
@atlas where are sessions refreshed? to search the workspace, or @atlas /impact
for what depends on the symbol at the cursor (or @atlas /impact billing.checkout.submit for one you name).
@atlas /remember decision: ... notes a fact. Answers link to the code, and a reply's thumbs rate it.
- For your AI assistant. BBM-Atlas's tools are offered to Copilot's agent mode as an MCP server, with nothing
to configure. These include search, impact analysis, graph paths and remembered facts. In Cursor, the extension
registers the server with Cursor's agent the same way. In other editors without VS Code's MCP API,
BBM-Atlas: Copy MCP Configuration gives you an entry in that editor's own format - Devin Desktop's
mcp_config.json, or Cursor's .cursor/mcp.json for a project - and says where to paste it.
- Fewer tokens for Claude Code. In a workspace that uses Claude Code, the extension offers to have BBM-Atlas
compress Claude Code's large tool outputs - test runs, git log, diffs, builds - before they reach the model. It
adds a hook to
.claude/settings.local.json and keeps it pointing at the server; when the server isn't running,
Claude Code sees its outputs unchanged.
- What it saved. The status bar shows the tokens BBM-Atlas saved your assistants today. The Token Savings view
shows today, the last 7 days and all time, with measured savings, estimated ones and BBM-Atlas's own cost apart.
- Context for a chat app. BBM-Atlas: Copy Context for a Chat App… copies a context pack for your question,
ready to paste into claude.ai, ChatGPT or the Gemini app in place of whole files. It holds the code the question
needs, where it is used, and its files' outlines.
- Tell your assistants when to use it. BBM-Atlas: Tell AI Assistants When to Use BBM-Atlas adds a short
section to
CLAUDE.md, AGENTS.md, GEMINI.md or Copilot's instructions, after asking.
New here? BBM-Atlas: Get Started opens a six-step walkthrough. Something wrong? BBM-Atlas: Report a
Problem… prepares a report of your setup and the log, with no keys in it, for you to read and send.
Commands
Everything is under BBM-Atlas: in the Command Palette.
| Command |
What it does |
| Search… |
Ask about the code, or find a symbol |
| Analyze Impact |
What depends on the symbol at the cursor (also in the editor's context menu) |
| Remember…, Find Facts… |
Note a fact about the folder you're in, or rank the Facts view's notes by some words |
| Find Path From Here To… |
The chain joining the symbol at the cursor to one you pick (also in the editor's context menu and the hover) |
| Show Import Cycles, Show Most-Connected Symbols |
A folder's import cycles, or the symbols with the most relationships, in the Graph Insights view |
| Show Graph Here |
The symbol at the cursor and its neighbours, drawn in a panel beside the editor |
| Show in Graph Explorer |
The symbol at the cursor in the console's graph view |
| Open Web Console |
The console: repositories, search, the graph and impact |
| Index Workspace, Re-index Workspace (full) |
Index the workspace's folders; the full run parses every file again |
| Start Server, Stop Server, Restart Server, Show Log |
Control the BBM-Atlas the extension runs |
| Install BBM-Atlas, Choose Python… |
Install or upgrade BBM-Atlas with pip, or pick another Python |
| Set API Key, Clear API Key |
The key of a BBM-Atlas server you connect to |
| Enter Licence Key, Clear Licence Key |
Your Enterprise Edition licence key |
| Copy MCP Configuration |
An MCP entry for editors that cannot be set up automatically |
| Set Up the Claude Code Hook, Remove the Claude Code Hook |
Have BBM-Atlas compress Claude Code's large tool outputs, or stop |
| Report a Problem… |
A report of your setup and the log, with no keys in it, to read and then send |
| Get Started |
The walkthrough: start, index, impact, search, facts and your AI assistant |
Settings
| Setting |
Default |
|
bbmAtlas.server.mode |
auto |
auto runs BBM-Atlas for this window; external connects to bbmAtlas.server.url |
bbmAtlas.server.url |
http://127.0.0.1:8000 |
The server for external mode |
bbmAtlas.server.port |
0 |
The port of the server this window starts. 0 keeps the one it had last time while it is free, so an MCP entry copied for another editor keeps working; pin one to be sure |
bbmAtlas.pythonPath |
|
The Python to run BBM-Atlas with; empty means find one |
bbmAtlas.index.onStartup |
true |
Index the workspace when the server starts |
bbmAtlas.index.onSave |
true |
Re-index a folder after a file in it is saved |
bbmAtlas.index.exclude |
[] |
What else to leave out of a folder's index, one .gitignore-style pattern each: vendor, *.min.js, src/generated/. Unset, the folder keeps the patterns it was indexed with |
bbmAtlas.impact.maxDepth |
3 |
How many hops impact analysis follows |
bbmAtlas.impact.includeTests |
false |
Also list the tests that cover what a change affects |
bbmAtlas.codeLens.enabled |
true |
Show the Impact code lens |
bbmAtlas.hover.enabled |
true |
Show callers and callees when hovering a symbol's name or a call to it |
bbmAtlas.mcp.enabled |
true |
Offer BBM-Atlas's tools to the AI assistant: Copilot's agent mode, or Cursor's agent in Cursor |
bbmAtlas.tokenSavings.statusBar |
true |
Show the tokens BBM-Atlas saved your assistants today in the status bar |
bbmAtlas.tokenSavings.view |
true |
Show the Token Savings view |
A shared server, and the Enterprise Edition
- Using a shared server. To use a BBM-Atlas your team runs, set
bbmAtlas.server.mode to external and
bbmAtlas.server.url to its address. Then run BBM-Atlas: Set API Key if it needs one.
- The Enterprise Edition adds people and roles, organisations, single sign-on, an audit log and high
availability. It is the same BBM-Atlas: BBM-Atlas: Enter Licence Key turns those features on in the server
the extension runs. Write to info@byteblendmatrix.com about a licence.
Keys are kept in VS Code's encrypted secret storage, never in settings.
Privacy and security
- Your code stays on your machine. BBM-Atlas runs locally, listens on the loopback address only, and keeps
each workspace's index in VS Code's storage for that workspace.
- Web pages can't use it. The server answers only requests addressed to
localhost or 127.0.0.1, so a page
in your browser can't reach it, and it indexes only the workspace's folders.
- No telemetry. The extension sends no usage data anywhere.
- Restricted Mode. The extension does not run Python or start a server in an untrusted workspace. Trust the
workspace to use it.
- Installing asks first. BBM-Atlas is installed only after you agree, and in a terminal you can see.
Requirements
- VS Code 1.101 or newer, or an editor compatible with it (Cursor, VSCodium and Devin Desktop, formerly
Windsurf, install from Open VSX).
- Python 3.11 to 3.14, on Linux, macOS or Windows.
- BBM-Atlas 1.0.0 or newer. The extension offers to install it, or to upgrade an older one.
- The extension works locally, over Remote SSH and WSL, and in dev containers. It runs where your code and
Python are.
Licence
BBM-Atlas is proprietary software under the BBM-Atlas License, included as LICENSE. The Community features are
free to use; the Enterprise features need a licence key.
| |