Skip to content

DocsUse

Claude Code

The BBM-Atlas plugin for Claude Code: BBM-Atlas's MCP server in every session, a skill that tells Claude which tool each task needs, and /bbm-atlas:index and /bbm-atlas:impact.

Installing the plugin

BBM-Atlas runs on your machine, so install it first. The plugin needs BBM-Atlas 1.0.0 or newer, on Python 3.11 or newer (pip install --upgrade bbm-atlas replaces an older one):

terminal
pip install bbm-atlas

Then, in Claude Code, add BBM-Atlas's marketplace and install the plugin from it:

terminal
/plugin marketplace add https://atlas.byteblendmatrix.com/claude/marketplace.json/plugin install bbm-atlas@byteblendmatrix

Claude Code asks for the BBM-Atlas command. Keep bbm-atlas when pip put it on your PATH (bbm-atlas --version answers in a terminal); otherwise give its full path in the environment you installed it into, such as /home/you/.venvs/atlas/bin/bbm-atlas. You can change it later in /plugin.

What it adds

PartWhat it does
BBM-Atlas's MCP serverStarted by Claude Code with each session: search, outline, read_symbol, analyze_impact, brief, index_repository and retrieve
The code-intelligence skillUsed by Claude whenever it works with code: index the project first, then the tool each task needs, and grep where none fits
/bbm-atlas:index [path] [--full]Indexes the project, or another path. Only changed files are parsed again unless you ask for --full
/bbm-atlas:impact <symbol>What changing a function, class or method affects: its dependents by file and line, and the tests to run

The skill routes by task: outline rather than reading a whole file, read_symbol with its callers before an edit, analyze_impact before changing code others use, and grep for exact strings and log messages. Claude Code sends a skill's one-line description with each request and the rest only when Claude uses it, so it costs less than instructions in CLAUDE.md.

How it works

  • Each Claude Code session starts its own BBM-Atlas server, which keeps its index in memory. The session indexes the repository once, and again after edits, when only the changed files are parsed.
  • Sessions don't share or lock anything, so several can run at once, beside a bbm-atlas serve too.
  • BBM-Atlas itself runs entirely on your machine. Claude sees what its tools answer, as with any other tool.

Sharing one index

To keep one index for every session and editor, run the server and connect Claude Code to it in your project, then turn the plugin's own server off in /mcp. The skills work with either:

terminal
bbm-atlas servebbm-atlas mcp install --host claude --url http://127.0.0.1:8000/mcp

With a server running, bbm-atlas hook install also has it compress Claude Code's large tool outputs, BBM-Atlas's own included, with the original a retrieve away. See Connect your assistant.

Updates

Each BBM-Atlas release publishes the plugin at the same version. To take it:

terminal
/plugin marketplace update byteblendmatrix

Or turn on auto-update for the marketplace: in /plugin, open Marketplaces, select it, and choose Enable auto-update.

When the tools don't appear

  • /mcp lists plugin:bbm-atlas:bbm-atlas and, when it didn't start, why. Most often the BBM-Atlas command isn't found: give its full path in /plugin.
  • bbm-atlas --version in a terminal checks the installation, and bbm-atlas doctor the rest of it.
  • A tool that says no repository is indexed needs /bbm-atlas:index first.